Localization/i18n Best Practices: Difference between revisions

From OLPC
Jump to navigation Jump to search
(New page: = General tips = Here are some general tips which will make your translators happy == When in doubt, use translator-comments == When you are writing a string which may be confusing for the...)
 
(migrated to SL)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Migrated to sl.o | http://wiki.sugarlabs.org/go/Translation_Team/i18n_Best_Practices }}
= General tips =
= General tips =
Here are some general tips which will make your translators happy
Here are some general tips which will make your translators happy
== When in doubt, use translator-comments ==
== When in doubt, use translator-comments ==
When you are writing 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)
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)
<pre>
<pre>
# TRANS: multiplication symbol (default: '*')
# TRANS: multiplication symbol (default: '*')
self.mul_sym = _('mul_sym')
self.mul_sym = _('mul_sym')
</pre>
</pre>
So as you can see from the above example, translator-comments are normal Python comments with the "TRANS" keyword.
So as you can see from the above example, translator-comments are normal Python comments with the "TRANS" keyword. This shows up the PO file as
<pre>
#. TRANS: multiplication symbol (default: '*')
#: mathlib.py:74
msgid "mul_sym"
msgstr ""
</pre>


== Use plural forms ==
== Use plural forms ==
Line 35: Line 42:




== Keep string formatting as less fancy as possible ==
== Keep string formatting as simple as possible ==


In case of code like the following example, translators tend to translate the strings "error" and "file" into their own languages, causing msgfmt to choke.
In case of code like the following example, translators tend to translate the strings "error" and "file" into their own languages, causing msgfmt to choke.
Line 44: Line 51:
</pre>
</pre>


Avoid such strings if possible.
Avoid such strings if possible; use numbers or untranslatable strings (that are not English words) instead, e.g.
<pre>
notify.props.msg = _('%(ERR)s when deleting %(2)s') % \
{ 'ERR': err.strerror, '2': logfile }
</pre>


= Pootle specific tips =
= Pootle specific tips =
Line 51: Line 62:
== Do not touch anything inside your po directory ==
== 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 yu 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 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.


== Try to keep the po directory in the top level directory of your repository ==
== 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 direcotry 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.
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.


[[Category:Language support]]
[[Category:Languages (international)]]
[[category:localization]]

Latest revision as of 03:01, 29 June 2009

542-stopicon.png    This page has been migrated to the Sugar Labs wiki.
This is an archive (and likely, out-of-date) copy of material found at http://wiki.sugarlabs.org/go/Translation_Team/i18n_Best_Practices .
Please edit and comment on it there.
If you disagree with its migration, please explain why on its talk page.

General tips

Here are some general tips which will make your translators happy

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)

        # TRANS: multiplication symbol (default: '*')
        self.mul_sym = _('mul_sym')

So as you can see from the above example, translator-comments are normal Python comments with the "TRANS" keyword. This shows up the PO file as

#. TRANS: multiplication symbol (default: '*')
#: mathlib.py:74
msgid "mul_sym"
msgstr ""

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 plural forms via ngettext() in these cases. Example (from sugar-update-control):

                header = gettext.ngettext("You can install %s update",
                                          "You can install %s updates", avail) \
                                          % avail


Use white-spaces and newlines only when you need to

The tool which converts the translated PO files into binary MO files, msgfmt, can be quite picky about newlines and lines with only whitespaces. For example, the following string in sugar has a blank line at the end which is often overlooked by translators, causing msgfmt to choke.

    print _('Usage: sugar-control-panel [ option ] key [ args ... ] \n\
    Control for the sugar environment. \n\
    Options: \n\
    -h           show this help message and exit \n\
    -l           list all the available options \n\
    -h key       show information about this key \n\
    -g key       get the current value of the key \n\
    -s key       set the current value for the key \n\
    -c key       clear the current value for the key \n\
    ')


Keep string formatting as simple as possible

In case of code like the following example, translators tend to translate the strings "error" and "file" into their own languages, causing msgfmt to choke.

                notify.props.msg = _('%(error)s when deleting %(file)s') % \
                    { 'error': err.strerror, 'file': logfile }

Avoid such strings if possible; use numbers or untranslatable strings (that are not English words) instead, e.g.

                notify.props.msg = _('%(ERR)s when deleting %(2)s') % \
                    { 'ERR': err.strerror, '2': logfile }

Pootle specific tips

These are some tips/guidelines which would keep Sayamindu (who currently maintains the Pootle installation) happy ;-).

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.

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.