Translation Team/i18n Best Practices: Difference between revisions

(13 intermediate revisions by 6 users not shown)

Line 1:

<noinclude>{{ GoogleTrans-en | es =show | bg =show | zh-CN =show | zh-TW =show | hr =show | cs =show | da =show | nl =show | fi =show | fr =show | de =show | el =show | hi =show | it =show | ja =show | ko =show | no =show | pl =show | pt =show | ro =show | ru =show | sv =show }} </noinclude>{{TOCright}}

= General tips =

Here are some general tips which will make your translators happy

Here are some general tips which will make your translators happy. For a much more comprehensive list of best practices, please read the [http://live.gnome.org/TranslationProject/DevGuidelines | Gnome i18n Guidelines].

== When in doubt, use translator-comments ==

When you are using a string which may be confusing for the translators (contextual issues, or cultural issues), or if you want the string to be translated according to a particular convention, use translator-comments, which would show up alongside the message in the PO file translator get when they translate you software. Example (from Calculate activity)

Line 13:

#: mathlib.py:74

msgid "mul_sym"

msgstr ""

</pre>

You can also use [http://www.gnu.org/software/gettext/manual/html_node/Contexts.html#Contexts msgctxt], which is better integrated with [http://en.wikipedia.org/wiki/Translation_memory Translation Memory] (T.M.). The output is in this form:

<pre>

#: string ID

msgctxt "button label"

msgid "Edit"

msgstr ""

</pre>

== Use plural forms ==

Do not assume that all languages have a concept of singular and plural like English. Some languages might have a single form, and some have more than two form. Use [http://www.gnu.org/software/~~automake~~/manual/gettext/Plural-forms~~.html~~ plural forms] via ''ngettext()'' in these cases. Example (from sugar-update-control):

Do not assume that all languages have a concept of singular and plural like English. Some languages might have a single form, and some have more than two form. Use [http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms plural forms] via ''ngettext()'' in these cases. Example (from sugar-update-control):

<pre>

header = gettext.ngettext("You can install %s update",

Line 24:

Line 32:

</pre>

== Show changes in strings ==

Use the "--previous" option with msgmerge when updating PO files. This option will output strings like this:

<pre>

#, string header

#|msgid "This is the old string"

msgid "This is the new string"

msgstr "This is the old string translated"

</pre>

so translators can see what has changed. Some translation editors will highlight the changes, which is particularly helpful with complex strings, very long strings or strings with code/formatting. This option definitely improves the accuracy of translation updates.

== Use white-spaces and newlines only when you need to ==

Line 62:

Line 79:

== Do not touch anything inside your po directory ==

If you change anything inside the po directory (including the POT file), and push it to Git, it will create a conflict which has to be updated in the Pootle side manually. Try avoid doing this, If you see any issues, please ping Sayamindu (sayamindu at ~~laptop~~ dot org) (you can also catch him on IRC, in channels like #sugar on Freenode with the nick unmadindu). If the changeset that you have is large, send him a patch, and he will apply that from the Pootle side manually and commit.

If you change anything inside the po directory (including the POT file), and push it to Git, it will create a conflict which has to be updated in the Pootle side manually. Try avoid doing this, If you see any issues, please ping Sayamindu (sayamindu at sugarlabs dot org) (you can also catch him on IRC, in channels like #sugar on Freenode with the nick unmadindu). If the changeset that you have is large, send him a patch, and he will apply that from the Pootle side manually and commit.

== Try to keep the po directory in the top level directory of your repository ==

The various homebrew helper scripts which keep Pootle running properly make the assume that the po directory will be in the toplevel of the source repository. Try to avoid putting the po directory under a directory like i18n or such, as this will need yet another special casing in the helper scripts, making stuff more difficult to maintain.

== Add user pootle to the committer list for your activity ==

If you have set up your activity on git.suagrlabs.org, please add the user pootle to the committer list so that po files can be updated for your project. (You add new committers from the button "Manage colaborators" in the right-hand menu on the repository mainline page (where you will find a link to http://git.sugarlabs.org/[your activity]/mainline).

== Request to have your project included in pootle ==

Make a request by filing a ticket on bugs.sugarlabs.org. You should set Type to 'task' and Component to 'localization'. Please include a link to the project page on git.sugarlabs.org (or whatever other repository you use).

== Specify the character encoding if necessary ==

Python files with non-ascii characters or declaring strings representing them, need to add the following line to the header.

# -*- coding: utf-8 -*-

If not, the pootle helper won't generate the pot/po files.

@@ Line 1: / Line 1: @@
 <noinclude>{{ GoogleTrans-en | es =show | bg =show | zh-CN =show | zh-TW =show | hr =show | cs =show | da =show | nl =show | fi =show | fr =show | de =show | el =show | hi =show | it =show | ja =show | ko =show | no =show | pl =show | pt =show | ro =show | ru =show | sv =show }} </noinclude>{{TOCright}}
 = General tips =
-Here are some general tips which will make your translators happy
+Here are some general tips which will make your translators happy.  For a much more comprehensive list of best practices, please read the [http://live.gnome.org/TranslationProject/DevGuidelines | Gnome i18n Guidelines].
 == When in doubt, use translator-comments ==
 When you are using a string which may be confusing for the translators (contextual issues, or cultural issues), or if you want the string to be translated according to a particular convention, use translator-comments, which would show up alongside the message in the PO file translator get when they translate you software. Example (from Calculate activity)
@@ Line 13: / Line 13: @@
 #: mathlib.py:74
 msgid "mul_sym"
+msgstr ""
+</pre>
+You can also use [http://www.gnu.org/software/gettext/manual/html_node/Contexts.html#Contexts msgctxt], which is better integrated with [http://en.wikipedia.org/wiki/Translation_memory Translation Memory] (T.M.). The output is in this form:
+<pre>
+#: string ID
+msgctxt "button label"
+msgid "Edit"
 msgstr ""
 </pre>
 == Use plural forms ==
-Do not assume that all languages have a concept of singular and plural like English. Some languages might have a single form, and some have more than two form. Use [http://www.gnu.org/software/automake/manual/gettext/Plural-forms.html plural forms] via ''ngettext()'' in these cases. Example (from sugar-update-control):
+Do not assume that all languages have a concept of singular and plural like English. Some languages might have a single form, and some have more than two form. Use [http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms plural forms] via ''ngettext()'' in these cases. Example (from sugar-update-control):
 <pre>
                  header = gettext.ngettext("You can install %s update",
@@ Line 24: / Line 32: @@
 </pre>
+== Show changes in strings ==
+Use the "--previous" option with msgmerge when updating PO files. This option will output strings like this:
+<pre>
+#, string header
+#|msgid "This is the old string"
+msgid "This is the new string"
+msgstr "This is the old string translated"
+</pre>
+so translators can see what has changed. Some translation editors will highlight the changes, which is particularly helpful with complex strings, very long strings or strings with code/formatting. This option definitely improves the accuracy of translation updates.
 == Use white-spaces and newlines only when you need to ==
@@ Line 62: / Line 79: @@
 == Do not touch anything inside your po directory ==
-If you change anything inside the po directory (including the POT file), and push it to Git, it will create a conflict which has to be updated in the Pootle side manually. Try avoid doing this, If you see any issues, please ping Sayamindu (sayamindu at laptop dot org) (you can also catch him on IRC, in channels like #sugar on Freenode with the nick unmadindu). If the changeset that you have is large, send him a patch, and he will apply that from the Pootle side manually and commit.
+If you change anything inside the po directory (including the POT file), and push it to Git, it will create a conflict which has to be updated in the Pootle side manually. Try avoid doing this, If you see any issues, please ping Sayamindu (sayamindu at sugarlabs dot org) (you can also catch him on IRC, in channels like #sugar on Freenode with the nick unmadindu). If the changeset that you have is large, send him a patch, and he will apply that from the Pootle side manually and commit.
 == Try to keep the po directory in the top level directory of your repository ==
 The various homebrew helper scripts which keep Pootle running properly make the assume that the po directory will be in the toplevel of the source repository. Try to avoid putting the po directory under a directory like i18n or such, as this will need yet another special casing in the helper scripts, making stuff more difficult to maintain.
+== Add user pootle to the committer list for your activity ==
+If you have set up your activity on git.suagrlabs.org, please add the user pootle to the committer list so that po files can be updated for your project. (You add new committers from the button "Manage colaborators" in the right-hand menu on the repository mainline page (where you will find a link to http://git.sugarlabs.org/[your activity]/mainline).
+== Request to have your project included in pootle ==
+Make a request by filing a ticket on bugs.sugarlabs.org. You should set Type to 'task' and Component to 'localization'. Please include a link to the project page on git.sugarlabs.org (or whatever other repository you use).
+== Specify the character encoding if necessary ==
+Python files with non-ascii characters or declaring strings representing them, need to add the following line to the header.
+  # -*- coding: utf-8 -*-
+If not, the pootle helper won't generate the pot/po files.