Edgewall Software

Changes between Version 124 and Version 125 of TracL10N


Ignore:
Timestamp:
Oct 28, 2012, 6:00:49 PM (7 years ago)
Author:
Christian Boos
Comment:

reviewing the page, a lot of minor updates

Legend:

Unmodified
Added
Removed
Modified
  • TracL10N

    v124 v125  
    22= Localization (L10N) of Trac =
    33
    4 Trac uses [http://babel.edgewall.org/ Babel] for localization. Starting with version [milestone:0.12], Trac contains the i18n framework and L10N files.
    5 
    6 The ''Preferences / Language'' panel can be used to select the language from the list of available translations, otherwise the web browsers' language preferences will be honored, if possible.
     4Trac uses [http://babel.edgewall.org/ Babel] for localization. Starting with version [milestone:0.12], Trac contains the i18n framework and L10N message catalog files.
     5
     6From the user point of view, the ''Preferences / Language'' panel can be used to select the language from the list of available translations, otherwise the web browsers' language preferences will be honored, if possible.
    77
    88If you're only interested in using a localized version of Trac, then nothing more than a standard TracInstall is needed, provided you installed Babel before.
    99
    10 The more complete installation instructions below are aimed at developers and translators, who want to contribute translations for Trac 0.12.x and 1.0dev.
     10The more complete installation instructions below are aimed at developers and translators, who want to contribute translations for Trac 0.12.x and beyond.
    1111
    1212Note that this whole page is dedicated to the technical details of translating the Trac web application. There's also a parallel effort to translate the TracGuide, see TracGuideTranslations. While there's much more "text" to translate there, there are also much less technical constraints, so if you're intimidated by what follows but nevertheless would like to contribute back to Trac by providing your language expertise, here's a nice alternative!
     
    1616=== Getting the Tool Chain ===
    1717==== Python Tools ==== #Pythontools
    18  1. Install [http://babel.edgewall.org/ Babel] version [Babel:wiki:Download#LatestRelease:0.9.5 0.9.5] or newer [[br]]
     18 1. Install [http://babel.edgewall.org/ Babel] version [Babel:wiki:Download#LatestRelease:0.9.6 0.9.6] or newer [[br]]
    1919    Read the [http://babel.edgewall.org/wiki/SubversionCheckout detailed installation instructions] for Babel if you want to build it from source, but you should also be able to install it with a simple `easy_install` or by using one of the packages in the Download page linked above.
    2020 1. Likewise, install [http://genshi.edgewall.org/ Genshi] version [Genshi:wiki:Download#LatestRelease:0.6 0.6],
    2121    using `easy_install` or by using one of the packages available for download.
    22  1. Get a svn checkout from the Trac release line you want to translate:
    23     - [[span(style=color: grey,[source:trunk] for 1.0dev, e.g. `svn checkout http://svn.edgewall.org/repos/trac/trunk trac-1.0dev`)]] (opened for translations)
    24     - [source:branches/0.12-stable] for 0.12.x, e.g. `svn checkout http://svn.edgewall.org/repos/trac/trunk trac-0.12.x` (opened for translations)
     22 1. Get a [TracRepositories source code checkout] for the Trac release line you want to translate:
     23    - [source:trunk] for 1.1.x, \\ e.g. `svn checkout http://svn.edgewall.org/repos/trac/trunk trac-1.0dev`
     24    - [source:branches/1.0-stable] for 1.0.x, \\ e.g. `svn checkout http://svn.edgewall.org/repos/trac/branches/1.0-stable trac-1.0dev`
     25    - [source:branches/0.12-stable] for 0.12.x, \\ e.g. `svn checkout http://svn.edgewall.org/repos/trac/branches/0.12-stable trac-0.12.x`
    2526
    2627All the discussion and examples below refer to `trunk`, but everything will work out exactly the same way for the `0.12-stable` branch or any other more recent branch.
     
    3031It is very important to not waste time translating an out-of-date catalog.
    3132
    32 In the repository, only the catalog **templates** ([source:trunk/trac/locale/messages.pot trac/locale/messages.pot] and [source:trunk/trac/locale/messages-js.pot trac/locale/messages-js.pot]) get updated regularly by Trac developers. If we would do so for the all the `.po` catalogs, this would generate lots of big and noisy changesets. So we leave that task up to the translators, which is something they should do before starting the actual translation work.
     33In the repository, only the catalog **templates** ([source:trunk/trac/locale/messages.pot trac/locale/messages.pot] and [source:trunk/trac/locale/messages-js.pot trac/locale/messages-js.pot]) get updated regularly by Trac developers. If we would do so for the all the `.po` catalogs, this would generate lots of big and noisy changesets. So we leave that task up to the translators, which is something they should do before starting the actual translation work or before integrating updates coming from contributors when they're acting as translation team coordinators.
    3334
    3435There are several different procedures to get the catalogs in sync with the templates, choose the one you're more comfortable with.
    3536
    3637==== Using Python tools ====
     38
    3739 1. Run `python setup.py extract_messages`. [[br]]
    3840    This will generate the catalog template file: 
     
    4547 1. Run `python setup.py update_catalog`. [[br]]
    4648    This will regenerate the various string catalogs
    47     (`trac/locale/*_*/LC_MESSAGES/messages.po`),
     49    (`trac/locale/*/LC_MESSAGES/messages.po`),
    4850    preserving the previously translated strings and merging the new
    4951    translations found in the messages.pot file. Translations that are
    5052    no longer needed are commented out (`#~`) and moved at the bottom of the
    51     .po file. [[br]]
     53    .po file (be careful, they will be discared by the next update, so if
     54    they contain valuable content, save it somewhere). [[br]]
    5255    Usually, you will be interested in working on one locale only, so you
    5356    can pass the `-l` option to specify which catalog should be updated.
     
    5760    extracted strings in the messages.po file for your language.
    5861    [[comment(See examples below.)]]
    59  1. Once you're done, you should test your translations:
     62 1. Once you're done, you should **validate** your translations:
    6063    1. Run `python setup.py update_catalog -l` again, for normalizing the
    6164      manual edits. For example: [[br]]
     
    6770      messages.pot file (as discussed in step 2. above) have been discarded
    6871      by this second `update_catalog` run.
    69     2. Run `python setup.py compile_catalog -f`. [[br]]
     72    2. Run `python setup.py check_catalog -f`. [[br]]
     73      This will search the catalog for common mistakes, like placeholder
     74      mismatches, invalid embedding in Genshi's structure messages, etc.
     75    3. Run `python setup.py compile_catalog -f`. [[br]]
    7076      This will generate one compiled catalog (`message.mo` file) for each
    7177      (or each specified) messages.po file. You don't need to do anything
     
    8490      Alternatively you can use `python setup.py develop` once for all,
    8591      if you want to be able to run Trac from your working copy.
    86 
    87 Note that you could stop at step 3, but then you risk to submit incomplete or,
    88 worse, buggy messages.po files. Going through the 4^th^ step will ensure a
     92      Beware that there's no ''on the fly'' compilation of the catalogs,
     93      so any change will have to go through step 4.3 (compile) before being
     94      visible in your Trac instance.
     95
     96If you skip the 4th step (validation), you risk to submit incomplete or,
     97worse, buggy messages.po files. Going through the 4th step will ensure a
    8998better quality standard. Finally, seeing your translations "live" in Trac is
    9099not only a great way to realize if the translation still makes sense once put
     
    92101wording ;-)
    93102
     103Note that the above was written at a time there was only //one// catalog file,
     104messages.pot. So in order to be complete, you'd have to repeat this for all
     105the catalogs:
     106 - `messages-js`
     107   - `extract_messages_js`
     108   - `update_catalog_js`
     109   - `check_catalog_js`
     110   - `compile_catalog_js`
     111   - `generate_messages_js` (the last step specific to Javascript i18n)
     112 - `tracini`
     113   - `extract_messages_tracini`
     114   - `update_catalog_tracini`
     115   - `check_catalog_tracini`
     116   - `compile_catalog_tracini`
     117
     118If this look tedious and you're thinking about scripting all of this... don't worry, that has already been done, see [#using-make] below.
     119
    94120==== Using `msgfmt` tools ====
    95121
    96122Although Babel is Python specific and is the tool which is advised to use,
    97 the traditional [http://linux.die.net/man/1/msgfmt msgfmt] toolset (part of GNU `gettext`) can also be used.
     123the traditional [http://linux.die.net/man/1/msgfmt msgfmt] toolset (part of GNU `gettext`) can also be used, but preferably for related tasks like checking the catalogs and getting statistics, rather than updating or the compiling the catalogs.
     124
    98125In particular, the following command is quite useful:
    99126{{{
     
    113140Some errors were detected with format specifications.
    114141
    115 This is a useful ''additional'' check, as `python setup.py compile_catalog -l zh_CN` wouldn't have detected that issue.
     142This is a useful ''additional'' check, as neither `python setup.py compile_catalog -l zh_CN` nor `python setup.py check_catalog -l zh_CN` wouldn't have detected that issue. FIXME //we detect mismatches, but not missing placeholders in `msgstr`//
    116143
    117144
     
    119146
    120147The web-based collaborative site for translations Transifex has
    121 a [Transifex: project page for Trac].
     148a [Transifex: project page for Trac] and its convenient user interface makes it very attractive for translators who don't want to mess directly with the source code.
    122149
    123150There, a number of "resources" (`.pot` messages catalog files in our case) are grouped in several "releases". Currently the "releases" corresponds to our maintenance branches.
     
    136163   - [Transifex:resource/trunk-tracini-pot 1.0-stable - trac/locale/tracini.pot]
    137164
    138 There, you can add translations directly online once you're member of a translation team, but in the end, the changes will have to be committed back to the source tree. See [./Transifex] sub page for more details.
    139 
    140 
    141 ==== The easy way using `make` and l10n targets ====
     165Once you're member of a translation team, you can add translations directly online. But in the end, the changes will have to be committed back to the source tree, so you better have to check beforehand with the translator coordinator of your language to see if is comfortable with getting updates from Transifex. If you are a translation team coordinator, please refer to the [./Transifex] sub page for more details.
     166
     167
     168==== The easy way using `make` and l10n targets ==== #using-make
    142169
    143170You'll find a Makefile in the toplevel directory of the Trac source.
     
    179206
    180207Example usage:
    181 {{{
     208{{{#!console
    182209$ make stats-pot update check compile stats locale='fr de'
    183210translation statistics for messages.pot:
     
    227254Then proceed through the steps listed [#Pythontools above] starting at step 2.
    228255
     256
    229257=== How far would you like to go?
    230258
     
    241269Those statistics reflect the coverage status of the `.po` files (catalogs) compared to the `.pot` files (catalog templates). The template catalogs themselves **might** be out-of-date compared to the source itself, though we regularly perform an automatic extraction.
    242270
    243  **0.12-stable** [[Image(http://www.transifex.net/projects/p/trac/resource/0_12-stable-messages-pot/chart/image_png, align=middle, title=go to the Trac page for 0.12-stable on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/0_12-stable/)]]
    244 
    245  **1.0-stable** [[Image(http://www.transifex.net/projects/p/trac/resource/1_0-stable-messages-pot/chart/image_png, align=middle, title=go to the Trac page for 1.0-stable on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/1_0-stable/)]]
    246 
    247  **trunk** [[Image(http://www.transifex.net/projects/p/trac/resource/trunk-messages-pot/chart/image_png, align=middle, title=go to the Trac page for trunk on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/trunk/)]]
    248 
    249 Kindly provided by [[Image(https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]]
     271|| ||= messages.pot ||= messages-js.pot ||= tracini.pot ||
     272||= 0.12-stable || \
     273|| [[Image(http://www.transifex.net/projects/p/trac/resource/0_12-stable-messages-pot/chart/image_png, align=middle, title=go to the Trac page for 0.12-stable on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/0_12-stable/)]] || \
     274|| [[Image(http://www.transifex.net/projects/p/trac/resource/0_12-stable-messages-js-pot/chart/image_png, align=middle, title=go to the Trac page for 0.12-stable on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/0_12-stable/)]] || \
     275|| ||
     276||= 1.0-stable || \
     277|| [[Image(http://www.transifex.net/projects/p/trac/resource/1_0-stable-messages-pot/chart/image_png, align=middle, title=go to the Trac page for 1.0-stable on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/1_0-stable/)]] || \
     278|| [[Image(http://www.transifex.net/projects/p/trac/resource/1_0-stable-messages-js-pot/chart/image_png, align=middle, title=go to the Trac page for 1.0-stable on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/1_0-stable/)]] || \
     279|| [[Image(http://www.transifex.net/projects/p/trac/resource/1_0-stable-tracini-pot/chart/image_png, align=middle, title=go to the Trac page for 1.0-stable on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/1_0-stable/)]] ||
     280||= trunk || \
     281|| [[Image(http://www.transifex.net/projects/p/trac/resource/trunk-messages-pot/chart/image_png, align=middle, title=go to the Trac page for trunk on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/trunk/)]] || \
     282|| [[Image(http://www.transifex.net/projects/p/trac/resource/trunk-messages-js-pot/chart/image_png, align=middle, title=go to the Trac page for trunk on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/trunk/)]] || \
     283|| [[Image(http://www.transifex.net/projects/p/trac/resource/trunk-tracini-pot/chart/image_png, align=middle, title=go to the Trac page for trunk on Transifex.net, link=https://www.transifex.net/projects/p/trac/r/trunk/)]] ||
     284
     285
     286Charts kindly provided by [[Image(https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]], based on the content of the catalogs uploaded there, which //should// correspond to the content of the catalogs in the repository.
    250287
    251288
     
    317354As with message parameters, the groups can be reordered but **you should
    318355have the same groups in `msgid` and `msgstr`** (see for example r9553).
     356The various `check_catalog_*` commands (`make check`) now look for such errors.
    319357
    320358Of course, you can have messages that combine markup groups and
     
    377415=== For Committers
    378416
    379 If you have commit access to the translation catalogs in the SubversionRepository, then you should be careful to commit only error-less updates. Translations can be fuzzy or missing, that's not a problem, but the errors spotted by `make check compile locale=<yourlocale>` should really be fixed before committing. Please also take care of [n:...] nestings, as those mistakes are **not** detected by the above automated checks and are quite deadly (#9171).
     417If you have commit access to the translation catalogs in the SubversionRepository, then you should be careful to commit only error-less updates. Translations can be fuzzy or missing, that's not a problem, but the errors spotted by `make check compile locale=<yourlocale>` should really be fixed before committing. Please also take care of fixing any `[n:...]` nestings errors reported by `make check`, as those mistakes are quite deadly (#9171).
    380418
    381419The commit message should have the following format:
    382420{{{
    383 l10n/<yourlocale>: <some message> (<xy>%)
     421<branch-name>/l10n/<yourlocale>: <some message> (<xy>%)
    384422
    385423<additional text if needed>
    386424}}}
     425`<branch-name>` can be omitted for trunk.
     426
    387427The percentage being the ratio of:
    388428{{{#!table class=""
     
    405445  title attributes::
    406446   those attributes are collected automatically (i.e. no need for explicit `${_('...')}` expressions), but only when the message doesn't contain an expression. In the latter case, they need an explicit `${_('... %(param)s ...', param=...)}` wrapping
    407  typographical translation:: some languages, like French, have special typographical rules (non breaking space before ":" or ";"), so don't consider that those signs can be left outside of translation scope when part of the text (e.g. `_(";")` when ";" is used as a separator, `_("%(field)s:")`)
     447 typographical translation:: some languages, like French, have special typographical rules (non breaking space before ":" or ";"), so don't consider that those signs can be left outside of translation scope when part of the text (e.g. use `_(";")` when ";" is used as a separator, `_("%(field)s:")` instead of `'%(field)s:'`)
    408448 messages consolidation::
    409   when adding new messages, always look if there's not already a very close message, and then reuse it (e.g. we now have 7 occurrences of ''"Repository '%(repo)s' not found"'', previously we had 7 variants of that message)
     449  when adding new messages, always look if there's not already a very close message, and then reuse it (e.g. we now have 7 //occurrences// of one single ''"Repository '%(repo)s' not found"'' message, previously we had 7 //messages//, each slightly different from the other!)
    410450 non-translatable messages:: in Genshi templates, you can use `xml:lang="en"` to mark the text in the element as not to be extracted (r10265)
    411451
     
    413453
    414454=== Open Issues === #Openissues
    415  - ''' help us spot the MissingTranslations! '''
     455 - ''' help us spot the MissingTranslations in the source code '''
     456 - some terms that should be translated are simply not present in the source code, but rather live in the TracIni or the database... but even for these nasty ones we have a plan: TracDev/Proposals/ConfigEnumTranslation
    416457 - translation of wiki pages (#1513) and help pages (TracDev/Proposals/NewHelp)
    417458