DocsProject common entities -- problem with translations?

[Dimitris Glezos]

Hi all.

The Docs Project is thinking of substituting entities like "Fedora 7" in all
documentation with "&FC;", so that these entities won't change with
each
upgrade. For example, now we have in the PO:

  This paragraph is about Fedora.

The change will make this:

 This paragraph is about &FED;.

Is there any language that would have a problem with this? One such problem
would be languages which change nouns ("Fedora") in different types of
sentences, for example:

 * "This is Fedora"
 * "These features of Fedora"
 * "Burn Fedora on a CD"

In greek we've left these untranslated and we won't have a problem. What about
other languages? Is everyone OK with this?

-d


-- 
Dimitris Glezos
Jabber ID: glezos(a)jabber.org, GPG: 0xA5A04C3B
http://dimitris.glezos.com/

"He who gives up functionality for ease of use
loses both and deserves neither." (Anonymous)
--

[Besnik Bleta]

I guess won´t be hard for a translator to fit that in a phrase
accordingly, like &FC-in, &FC-së, &FC-it (examples from sq), assuming
tha we are not allowed to spell Fedora differently when a language
requires it (again example from sq: Fedora, Fedoran, Fedoras,).

Dimitris Glezos wrote:
>  Hi all.
>  
>  The Docs Project is thinking of substituting entities like "Fedora 7" in all
>  documentation with "&FC;", so that these entities won't change with
> each
>  upgrade. For example, now we have in the PO:
>  
>    This paragraph is about Fedora.
>  
>  The change will make this:
>  
>   This paragraph is about &FED;.
>  
>  Is there any language that would have a problem with this? One such problem
>  would be languages which change nouns ("Fedora") in different types of
>  sentences, for example:
>  
>   * "This is Fedora"
>   * "These features of Fedora"
>   * "Burn Fedora on a CD"
>  
>  In greek we've left these untranslated and we won't have a problem. What about
>  other languages? Is everyone OK with this?
>  
>  -d
>  
>

[Alan Cox]

On Wed, Apr 04, 2007 at 11:20:59PM +0300, Besnik Bleta wrote:
>  I guess won??t be hard for a translator to fit that in a phrase
>  accordingly, like &FC-in, &FC-së, &FC-it (examples from sq), assuming
>  tha we are not allowed to spell Fedora differently when a language
>  requires it (again example from sq: Fedora, Fedoran, Fedoras,). 
Please don't make Fedora Core an entity, all sorts of things happen to
words depenidng upon their context and language particularly they may
acquire subject/object/dative etc endings, they may be subject to lentition
and there are languages were prepositions are themselves word endings. Just
try the latin translation for an example...

["Piotr \"Raven\" Drąg"]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dimitris Glezos napisał(a):
>  Is there any language that would have a problem with this? One such
> problem
>  would be languages which change nouns ("Fedora") in different types of
>  sentences, for example:
>  
>   * "This is Fedora"
>   * "These features of Fedora"
>   * "Burn Fedora on a CD"
>   
In Polish it should be:

 * "To jest Fedora"
 * "Te funkcje Fedory"
 * "Nagraj Fedorę na CD"

>  In greek we've left these untranslated and we won't have a
> problem. What about
>  other languages? Is everyone OK with this?
>   
In Polish unchanged nouns look very bad and simply ugly. I don't think
it's acceptable.

- --
Piotr "Raven" Drąg
http://raven.pmail.pl/
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.7 (GNU/Linux)
>
> iD8DBQFGFA6BjBBsaE0M6qkRAqFeAJ0QgIU3etLGPKketxMlQKdh5eqbtgCgrrRd
> VgYAuxT7x7q0WAsdEF2Sa1w=
> =G2sx
> -----END PGP SIGNATURE-----

[Vojtěch Horký]

Piotr 'Raven' Drąg napsal(a):
>  -----BEGIN PGP SIGNED MESSAGE-----
>  Hash: SHA1
>
>  Dimitris Glezos napisał(a):
>    
> > Is there any language that would have a problem with this? One such problem
> > would be languages which change nouns ("Fedora") in different types of
> > sentences, for example:
> > In greek we've left these untranslated and we won't have a problem. What
> about
> > other languages? Is everyone OK with this?
>
>  In Polish unchanged nouns look very bad and simply ugly. I don't think
>  it's acceptable.
>     
I completely agree with Piotr. With Czech it is the same - if you put 
everywhere just Fedora (in the basic form), it looks bad and sounds 
strange (and it is not gramatically correct). Moreover, I don't see any 
big advantage in using such entities - I am afraid they would just make 
things more complicated.
- Vojta

[Magnus Larsson]

Swedish (sv) is ok, if it is only trademarks and product names (that should
not be translated anyway). The name does not change in Swedish. However,
"The Fedora Docs Project is good." would be
"Fedora Docs Project är bra."
in Swedish since the "The" does not exist in Swedish.

My guess is that this gives more headache than it is worth, unless you plan
to change the Fedora-name into something else in the future...

-Magnus.

On 4/4/07, Dimitris Glezos <dimitris(a)glezos.com&gt; wrote:
>  Hi all.
>
>  The Docs Project is thinking of substituting entities like "Fedora 7" in
>  all
>  documentation with "&FC;", so that these entities won't change with
> each
>  upgrade. For example, now we have in the PO:
>
>    This paragraph is about Fedora.
>
>  The change will make this:
>
>  This paragraph is about &FED;.
>
>  Is there any language that would have a problem with this? One such
>  problem
>  would be languages which change nouns ("Fedora") in different types of
>  sentences, for example:
>
>  * "This is Fedora"
>  * "These features of Fedora"
>  * "Burn Fedora on a CD"
>
>  In greek we've left these untranslated and we won't have a problem. What
>  about
>  other languages? Is everyone OK with this?
>
>  -d
>
>
>  --
>  Dimitris Glezos
>  Jabber ID: glezos(a)jabber.org, GPG: 0xA5A04C3B
>  http://dimitris.glezos.com/
>
>  "He who gives up functionality for ease of use
>  loses both and deserves neither." (Anonymous)
>  --
>
>  --
>  Fedora-trans-list mailing list
>  Fedora-trans-list(a)redhat.com
>  https://www.redhat.com/mailman/listinfo/fedora-trans-list
>

[Paul W. Frields]

So it sounds like we will have annoyances no matter which choice we
make:

1.  Using "xml2po -k" and keeping entities intact like &NAME; there are
translators who will be inconvenienced.  They can still substitute
translations for the entity -- using the right form of "SomeName,"
instead of the exact string "&NAME;" -- but there will be no benefit to
them in the event the entity changes.  They may not even notice that it
*has* changed unless they are watching the
docs-common/common/entities/po/entities.pot file, and making the mental
connection.

2.  Using "xml2po -e" and transforming the entities into strings in the
POT file, so "&NAME;" becomes "SomeName," it will be painful to
change
single strings in a minor way, since *many* fuzzy entries potentially
result from trivial changes.

We can revert to behavior #2, and I can get this into the POTs for
important modules now.  I would like opinions within the next 24 hours.
We first raised this issue almost two weeks ago in our meeting,
summarized here:

https://www.redhat.com/archives/fedora-docs-list/2007-March/msg00186.html

Reminder to translators working on documentation:  please make sure you
are subscribed to fedora-docs-list(a)redhat.com for information.  Thank
you and we look forward to hearing from you about this issue.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Dimitris Glezos]

O/H Paul W. Frields έγραψε:
>  So it sounds like we will have annoyances no matter which choice we
>  make:
>  
>  1.  Using "xml2po -k" and keeping entities intact like &NAME; there are
>  translators who will be inconvenienced.  They can still substitute
>  translations for the entity -- using the right form of "SomeName,"
>  instead of the exact string "&NAME;" -- but there will be no benefit to
>  them in the event the entity changes.  They may not even notice that it
>  *has* changed unless they are watching the
>  docs-common/common/entities/po/entities.pot file, and making the mental
>  connection.
>  
>  2.  Using "xml2po -e" and transforming the entities into strings in the
>  POT file, so "&NAME;" becomes "SomeName," it will be painful to
> change
>  single strings in a minor way, since *many* fuzzy entries potentially
>  result from trivial changes. 
So, we (translators) need to decide here:

  1. Following 1., some translators behave differently than the others and
hard-translate the entities (substitute "&NAME;" with "Somename")
when they need
to. When an entity changes ("&FOO;" becomes "Fedora 8") the
translator will have
to manually update all occurrences for this language of "Fedora 8" to
"Fedora 9".

  2. All languages will get fuzzy translations once an entity changes. All of
them will have to do the job described in 1.

So, the Q is: How often does an entity change and how big is this change? At
this period we are changing "Fedora Core" -> "Fedora" and
"Fedora Core 6" ->
"Fedora 7". Later we'll probably only do the latter every 6 months.

If we choose 1, we can make sure that we notify those language teams that
substitute the entities that the entities have changed. They can then
search-and-replace all their files and substitute everything at the same time
(with a tool like `regexxer`). So 1. might not be as bad as it sounds after all.

What do the translators of the languages in question think about this?

>  We can revert to behavior #2, and I can get this into the POTs for
>  important modules now.  I would like opinions within the next 24 hours.
>  We first raised this issue almost two weeks ago in our meeting,
>  summarized here:
>  
>  https://www.redhat.com/archives/fedora-docs-list/2007-March/msg00186.html
>
>  Reminder to translators working on documentation:  please make sure you
>  are subscribed to fedora-docs-list(a)redhat.com for information.  Thank
>  you and we look forward to hearing from you about this issue. 
Unfortunately I didn't catch this problem back then and I almost missed it some
days ago because in greek we don't have it. More translators' eyes on -docs-list
mean more chances to catch these problems on time. :-)

-d


-- 
Dimitris Glezos
Jabber ID: glezos(a)jabber.org, GPG: 0xA5A04C3B
http://dimitris.glezos.com/

"He who gives up functionality for ease of use
loses both and deserves neither." (Anonymous)
--

[Paul W. Frields]

On Fri, 2007-04-06 at 02:58 +0100, Dimitris Glezos wrote:
>  O/H Paul W. Frields έγραψε:
>  > So it sounds like we will have annoyances no matter which choice we
>  > make:
>  > 
>  > 1.  Using "xml2po -k" and keeping entities intact like &NAME; there
> are
>  > translators who will be inconvenienced.  They can still substitute
>  > translations for the entity -- using the right form of "SomeName,"
>  > instead of the exact string "&NAME;" -- but there will be no benefit
> to
>  > them in the event the entity changes.  They may not even notice that it
>  > *has* changed unless they are watching the
>  > docs-common/common/entities/po/entities.pot file, and making the mental
>  > connection.
>  > 
>  > 2.  Using "xml2po -e" and transforming the entities into strings in the
>  > POT file, so "&NAME;" becomes "SomeName," it will be painful
> to change
>  > single strings in a minor way, since *many* fuzzy entries potentially
>  > result from trivial changes.
>  
>  So, we (translators) need to decide here:
>  
>    1. Following 1., some translators behave differently than the others and
>  hard-translate the entities (substitute "&NAME;" with "Somename")
> when they need
>  to. When an entity changes ("&FOO;" becomes "Fedora 8") the
> translator will have
>  to manually update all occurrences for this language of "Fedora 8" to
> "Fedora 9".
>  
>    2. All languages will get fuzzy translations once an entity changes. All of
>  them will have to do the job described in 1.
>  
>  So, the Q is: How often does an entity change and how big is this change? At
>  this period we are changing "Fedora Core" -> "Fedora" and
> "Fedora Core 6" ->
>  "Fedora 7". Later we'll probably only do the latter every 6 months. 
Some entities change less often, others more often.  In the future I
expect us to have a more robust test cycle for documentation, and you'll
be looking at monthly changes for things like "test2" => "test3". 
A
small change, but it would echo throughout many, many documents and
message strings.

>  If we choose 1, we can make sure that we notify those language teams
> that
>  substitute the entities that the entities have changed. They can then
>  search-and-replace all their files and substitute everything at the same time
>  (with a tool like `regexxer`). So 1. might not be as bad as it sounds after all. 
-1 "we notify"; scaling problem
+1 subscriptions to fedora-docs-commits(a)redhat.com

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Nicolas Mailhot]

Le Ven 6 avril 2007 03:58, Dimitris Glezos a écrit :

>  If we choose 1, we can make sure that we notify those language teams
> that
>  substitute the entities that the entities have changed. They can then
>  search-and-replace all their files and substitute everything at the same
>  time 
If your problem is only updating release versions, why don't you just make
an entity with the number ? The number alone won't have the grammar
problems of the full release string

-- 
Nicolas Mailhot

[Karsten Wade]

On Fri, 2007-04-06 at 08:22 +0200, Nicolas Mailhot wrote:
>  Le Ven 6 avril 2007 03:58, Dimitris Glezos a écrit :
>  
>  > If we choose 1, we can make sure that we notify those language teams that
>  > substitute the entities that the entities have changed. They can then
>  > search-and-replace all their files and substitute everything at the same
>  > time
>  
>  If your problem is only updating release versions, why don't you just make
>  an entity with the number ? The number alone won't have the grammar
>  problems of the full release string 
You are right, that we could solve the numeric problems easily.

And I see from the posts on f-trans-l that it is impossible for us to
use entities for many/most words.

It might help if it was understood what types of the problems that
entities traditionally solve for technical writing.  

Example uses are:

        * A technical writer is working on content that involves using
        multiple GUI tools, such as system-config-securitylevel and
        setroubleshoot.  The tool system-config-securitylevel also has a
        name in the GUI, Security Level Configuration.  To write the
        documentation, the writer is going to refer to these
        applications multiple times.  In each situation, the writer is
        going to need to write:
        
        <command>system-config-securitylevel</command>
        <command>setroubleshoot</command>
        <application>Security Level Configuration</application>
        
        At each typing, errors might be introduced.  Macros could be
        used, which are not a very DocBook XML way of doing things, but
        that could be sufficient.  However, it doesn't take care of the
        other example ...
        
        * Dan Walsh decides that "setroubleshoot" should really be an
        action name, so he changes it to "setroubleshooter".  Without an
        entity, changing that is a mildly complex search and replace
        operation.  In some cases, changing a name can require a grammar
        check.  In English, for example, the articles "a" and "an"
are
        used differently.  If Dan changed the name to
        "troubleshootselinux", the writer would need to check every
        article that appeared before the searched-and-replaced text.
        
FWIW, both of those things have happened to me (although Dan Walsh had
nothing to do with it :).  I had a product name change, but fortunately
it was the removal of the word "Enterprise" in the middle of the product
title.  I updated the entity, rebuilt six books, and went on to
something else for the afternoon.  In other situations that happened to
me, I has to to carefully edit grammar after an entity change.

As I look through this, three things are apparent:

1. It's more work on writers without ff entities.
2. It's impossible in some languages for entities to work.
3. Numbers are safe to use for entities, some trademarks may be safe to
use, e.g.
   <!ENTITY FEDVER  "7" >
   <!ENTITY IBM "<trademark
class="registered">IBM</trademark>" > 
   <!ENTITY S390 "S/390" >
   ... oh, no way, that has to change to ...
   <!ENTITY S390 "System Z" >

It seems that the writers have to accept the "more work", which could
include coming up with a clever solution to the whole situation.  More
likely, we'll just muddle through somehow.

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

[Nicolas Mailhot]

Le Ven 6 avril 2007 11:18, Karsten Wade a écrit :

>  It might help if it was understood what types of the problems that
>  entities traditionally solve for technical writing. 
Entities have historically been used mostly to declare non-ascii symbols,
which is not necessary anymore in an UTF-8 unicode work

They also work for technical stuff which does not appear in text discourse
and is not supposed to be translated (Copyright strings, etc)

Any other use fails in an international context (but happens in
mono-locale works)

-- 
Nicolas Mailhot