Re: UI strings vs manual strings ?

Thank you all for the replies so far.

Let me reply in one mail.

> On Dec 6, 2022, at 21:44, Tony Graham <[email protected]> wrote:
>=20
>> Problem at hand:
>> - a Java application with ~2k UI strings (not all users facing), in
>> a Bundle.properties file
>=20
> Java also has an XML format for properties files.

Interesting. It could be part of a solution (esp. considering =
Florimond's reply).

>> - a ~80K words DocBook manual
>> It is not trivial to keep track of the whole string set (searches, =
etc.)
>> Also, the l10n process takes place on the DocBook sources, not on
>> the HTML output, so tricks like <link linkend endterm/> don't work =
because translators don't see the target terms.
>=20
> Before translation, replace each <link/> with the replacement text =
from
> the XML properties file wrapped in a well-known element that still
> carries the identifier for the properties file entry.
>=20
> After translation, if necessary, convert the well-known elements back
> into <link/> and also do something to handle the strings that have =
been
> translated differently in different places.

The problem is that it's not possible to do that for a lot of languages. =
There are inflected forms that transform the text of the "endterm" part =
and the translation targets 3 dozen languages, including BiDi documents.

That process would add another layer of transformation+verification.

Or maybe I missed something?

> Once you have the properties file for a second language, you could
> insert the translated strings in place of <link/> when preparing for
> translation.  Alternatively, or as well, you could set up your
> computer-aided translation tool to not translate the well-known =
elements
> for the strings and insert the translated strings after everything =
else
> is translated.

It looks feasible but only with a small set of target languages.

>> I'm left with having to rewrite the strings explicitly and that's a =
pain, and also adds risks of mistakes in translations.
>=20
> The more that you can automate, the better.

Hence the question ;-)


> On Dec 6, 2022, at 22:04, Alemps Florimond <[email protected]> =
wrote:
>=20
> Hello,
>=20
> I would transform the bundle.properties in a document (article, book =
or section whatever)
> Each line of the file corresponds to somethine like :
> <simpara><guilabel xml:id=3D"messageId">My =
message</guilabel></simpara>
>=20
> One element simpara for one guilabel is useless : it is just to make =
it readable in a DocBook parse.

Interesting.

Considering that Java properties can also be expressed as XML there =
could be some automation here.

> In the document, you include the message - something like :
> <para>You should see <xi:include href=3D"bundle.properties.xml" =
xpointer=3D"messageId"> after clicking on the button.</para>
>=20
> The French, English, German version of the document will take =
advantage of the corresponding translated version of =
bundle.properties.xml

Why only those 3 languages?

My understanding of xi:include is that it is not required to be resolved =
before the actual documentation build process.

Which means that the document to translate (and the way it is displayed =
in the tool) is actually

> <para>You should see <arbitrary link shortcut> after clicking on the =
button.</para>

Which is not different from what we have now with <link linkend =
endterm/>

> As far as no id message starts with a number (NC Name for xml:id) you =
are ok.
> With an XSLT 2.0 processor, it might even be possible to transform the =
bundle.properties in XML.

It looks like Java properties can be expressed as XML natively (see =
above) so there is something to explore here.

> On Dec 7, 2022, at 5:13, Jan Tosovsky <[email protected]> wrote:
>=20
> On 05/12/2022 23:05, Jean-Christophe Helary wrote:
>> What's the best way in a DocBook centered process to ensure that the=20=

>> list of terms used in a software UI is (semi-automatically?) taken=20
>> into account in the DocBook sources that describe that software?
>=20
> In your document you can use <guilabel> and other <gui* related =
elements
> which can indicate the content must match the GUI label. You can then
> instruct the localization agency to follow this rule.
> But there is no way to avoid human error so this still has to be =
checked
> manually which is inefficient.=20

The problem is not instructions, the problem is to lower the burden of =
the translators by explicitly displaying the strings in the DocBook =
sources.

Creating a normative glossary from the UI strings first could be =
something, but there are Windows/Linux mnemonics (&) characters in the =
strings so we'd need to remove them to create that glossary and that =
would add another step (which can be automatized I guess).

Full disclosure: the manual is for OmegaT, a free software solution for =
translators, that supports DocBook out of the box, and Java properties =
too. I am project leader, also in charge of the manual, I made a close =
to full rewrite of the thing this summer/fall to prepare for our next =
release but I know that the solution that I chose (link linkend endterm) =
is not optimal because the link contents/target is not available for =
inflected modifications required in some languages. (And I also happen =
to be a translation company, so I understand those issues quite well, =
but it was my first time on the DocBook authoring side, the last time I =
wrote the manual it was in HTML.)

As mentioned above in the reply to Tony, the issue with some strings is =
that they must be explicitly available for translation because some =
languages need to modify them (grammatical inflections, etc.)

> I've seen an interesting approach where any guilabel had a dedicated
> attribute storing a termbase ID. While a guilabel value was present, =
it was
> just informative (for the author, to understand the context). The =
actual
> value was taken from the termbase during generating outputs.
>=20
> So if GUI labels are linked to the same termbase, this system ensures =
your
> document will never diverge. Moreover, it is ensured also to all =
translated
> documents.=20

I'm not sure I understand how the termbase is linked to the document.

> The hardest step is consolidating such a termbase and establishing =
processes
> on DEV and DOC sides so both departments use the termbase as a single =
source
> of truth.

:-)



--=20
Jean-Christophe Helary @[email protected]
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/