From kde-i18n-doc  Tue Aug 31 13:49:36 2004
From: Lauri Watts <lauri () kde ! org>
Date: Tue, 31 Aug 2004 13:49:36 +0000
To: kde-i18n-doc
Subject: Re: Question on docs
Message-Id: <200408311549.40650.lauri () kde ! org>
X-MARC-Message: https://marc.info/?l=kde-i18n-doc&m=109396031612111
MIME-Version: 1
Content-Type: multipart/mixed; boundary="--nextPart24910124.YgfaFMDJnW"

--nextPart24910124.YgfaFMDJnW
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

On Tuesday 31 August 2004 15.11, Funda Wang wrote:
> Hello,
>
> I want to translate the docs of kde and its apps. The PO files seem fine =
to
> me. But, how can I get the entities translated?
>
> i.e.: msgid "The &kcontrolcenter;"

There are two sets of entities: Those that should not be translated (they a=
re=20
the name of the application, contain trademarks, or for some other reason=20
must appear exactly as written) and those that should.

The ones that are not translated are defined here:=20
kdelibs/kdoctools/customization/entities/general.entities
In general things in this file are untranslateable on purpose.=20

The ones that should be translated:
kdelibs/kdoctools/customization/<LANG>/user.entities
You may translate this file in place, and it's ok to update this one in the=
=20
BRANCH as well as HEAD (I recommend you alter HEAD and backport it, so you=
=20
don't forget to do the HEAD one, as has happened a couple of times before.)

You may define any additional entities you like in /<yourlang>/user.entitie=
s,=20
for anything that you regularly find yourself using, even if we don't have =
an=20
equivalent entity in English.  There are many cases where a common phrase i=
n=20
one language, is better said several ways in another.
You are not in any way bound to use an entity just because there is one in =
the=20
original doc.=20
Even if you do want to use the entities, you don't have to use the same=20
declaration as in English.

Example 1:
&kcontrolcenter; is the name of the application.   Most languages don't=20
translate these, so it is a global entity.  If you do translate it in your=
=20
language, you could define a different entity in user.entities (for instanc=
e,=20
&zhkcontrolcenter; and in your translation, use that instead) or you can=20
simply type in the whole name of the application in your own language (don'=
t=20
forget to mark it <application>....</application>.  Make sure the name is=20
unique, unexpected things may happen if there are two definitions with the=
=20
same name.

Example 2:
In english, we say "e.g., ..." and have an &eg; (because even though it's o=
nly=20
a couple of letters, it's also an abbreviation and there are multiple ways =
to=20
punctuate it, so we made an entity so it's easy to be consistent in all the=
=20
docs.    "For example" isn't always abbreviated to "e.g." in every language=
,=20
so there's two ways to deal with it:
In the danish user.entities file, it is instead:
<!ENTITY eg     "<abbrev>f.eks.</abbrev>">
so &eg; will generate f.eks in Danish.
The french team have taken another approach, by translating both sides of t=
he=20
equation. =20
<!ENTITY pex                    "par exemple">=20
In French docs therefore, instead of using &eg; they would put &pex; and th=
e=20
text generated would be par exemple.
Either way works perfectly well, pick whichever suits you.

The French team also define a lot of their own entities, so they are a good=
=20
example to learn from.  That file is pretty much entirely your own=20
playground, you can add anything that is useful to you.=20

The only caveat is that once you have defined an entity there, you can't=20
remove it.  You can deprecate it, but it must stay in the file until the=20
next+1 DTD version, for reasons of backward compatibility.   Look at genera=
l=20
entities (near the bottom) for how we deal with that.

Regards,
=2D-=20
Lauri Watts
KDE Documentation: http://docs.kde.org
KDE on FreeBSD: http://freebsd.kde.org

--nextPart24910124.YgfaFMDJnW
Content-Type: application/pgp-signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (FreeBSD)

iD8DBQBBNIH0/gUyA7PWnacRAuULAKCTfyFfbQK7/ZB+mLnxKc5ITLmomQCfXUsi
JeaflKgrCretE8NZ/iiR7ZM=
=B6Dj
-----END PGP SIGNATURE-----

--nextPart24910124.YgfaFMDJnW--