[[PageOutline(2-5,Contents,pullout)]]

= Proposal for translation of configurable labels

== The Problem

We have translatable messages since Trac-0.12, even extended the i18n system towards configuration option doc-strings. But we're still missing translations in some rather prominent places, mostly related to terms that are meant to be customized in Trac installations.

See also [[TracL10N/Transifex]]

== Currently untranslatable items

This is a list of items, that can't be localized yet (including related tickets):
 * Enum
  * ticket properties:
   * type
   * status (see configurable ticket workflow below)
   * priority
   * severity
   * milestone (see below)
   * customized labels for standard fields (see #6249)
  * milestone label, used in tickets too
  * component name, used in tickets too
 * configurable ticket workflow
  * action name (see #9472)
  * ticket status, used in tickets and timeline as well, `new` and `closed` even hard-coded in ticket system code, including reports and custom queries (see #9799)
 * timeline
  * ticket changes (related to ticket status from work-flow above, see #5441)
 * customized standard templates and additional custom templates
 * `label`s in TracNavigation

Those are also present for now in MissingTranslations (listed by module), although that page should be dedicated to terms that could be translated using the current markers and which are simply missing them. 

Here we'll focus on terms that are meant to be customized and are found in the database or in the TracIni file rather than in the code.

== A possible solution

The following rough sketch of a suitable translation work-flow sprung from a discussion on IRC (25-Oct-2012):
 * `$ trac-admin <env> extract_custom_messages`
  a. produces a new file `env/htdocs/locale/trac_custom.pot` or
  b. updates an existing one
 * use similar standard procedures for `.po` files (more `trac-admin` commands here)
  * create new message catalogs for a language
  * update one/all existing messages catalogs
 * use standard procedures to edit message catalogs

Or, alternatively:
 * `trac-admin <env> localize` and subcommands:
   - `extract` -- creates or updates the `<env>/locale/custom.po` file
   - `init fr` -- creates the `<env>/locale/fr/LC_MESSAGES/custom.po` file from `<env>/locale/fr/LC_MESSAGES/custom.po`, if it doesn't exist yet
   - `update fr` -- updates that file
   - `compile fr` -- compiles that file into `<env>/locale/fr/LC_MESSAGES/custom.mo`
 * `trac-admin <env> localize ` //`subcommand`//` *` operates on all present catalogs (except for `init`)
 * `trac-admin <env> initenv` copies into `<env>/locale` all the already available `custom` related files, containing the translation for the "base" terms (e.g. the workflow states for the default terms, [#Wishlist 2.] below)

=== Implementation details

The aforementioned work-flow implies, that custom message cataloges are rather volatile. But recompilation on Trac environment load should be avoided, because this could be rather time-consuming. So it must be possible to pre-compile them, i.e. with yet another `trac-admin` command.
 ''cboos - I agree. Let's not try to work with .po files directly (if that was what you implied). Trac should only consider the present `.mo` files obtained from a `trac-admin <env> localize compile`. ''

=== Wishlist

(Order should matter)

 1. auto-generated TRANSLATOR hints like
  `# ini:ticket-workflow` or `# enum:priority`
   - alternatively, if there's no //source// file, that line could be faked: 
     {{{
#: ticket/enum/priority:2
msgid "high"
     }}}
 2. include a ''basic common'' set of typical terms, like work-flow action names from default ticket work-flow
 3. detect changes, to remind for recompilation, if pending changes are detected, but PO (clear-text) and MO (compiled) message catalog files change time must be tracked like done for `trac.ini` to make this happen
   - a macro could take care of this? `[[TracAdminLocalizeStatus(format=stats,lang=fr)]]` / `[[TracAdminLocalizeStatus(format=table)]]`