Translation process
===================

Note that most of the process must take place in the development environment.
This ensures that message translations and translators access rights are stored in the version control repository.
The only part of the process done in the production environment is the message validation or changes by the translators.


1. Check messages to translate
------------------------------

- go to "scripts"
- run "check_translations"

- if "obsolete english message ids" are reported:
* comment these messages in "data/translations/en.php"
* note that message ids must not be reused

- if "obsolete translation in action ids" are reported:
* remove these messages in "data/translations_in_action.php"

- if "missing english messages" are reported:
* add each message in the corresponding section of "data/translations/en.php"
* add a new section at the end if the message does not fit in an existing section (see the note on sections)
* use the next available message id

- if "missing translation in action ids" are reported:
  proceed as explained in 3. Updade the translations in action

Note that "missing translated message ids" and "obsolete translated message ids" are not used in this step.

Note on sections:
- a section corresponds to a logical unit of the interface, eg the top bar messages, the home page messages etc.
- a section begins with a message id that is a multiple of 100, and the section title, eg "Top bar", "Home page" etc.
- if you need to add a new section


2. Machine translate new messages
---------------------------------

For each new message:
- machine translate the message in each language with google or bing etc.
- add the translation in each language in the corresponding translation file, eg "data/translations/fr.php" for French
  use the same message id as the original message in English in "data/translations/en.php"

- run "check_translations" (again)


3. Updade the translations in action
------------------------------------

- if "obsolete english message ids" are reported, remove the corresponding entries in "data/translations_in_action.php"

For each "missing english messages" reported:
- add an entry in "data/translations_in_action.php"
* go to eg "http://php-by-example.local/fr/translation"
* select one language
* enter the admin credentials
* select the message
* click on "See the current translation in action" to verify the translation is properly highlighted


4. Double-check messages to translate
-------------------------------------

- run "check_translations" (again)
- verify that no
  "missing translated message ids", "obsolete english message ids", "missing english messages",
  "obsolete translation in action ids", "missing translation in action ids"
  are reported

Note that "obsolete translated message ids" are not used in this step.


5. Prepare the validation of the translations
---------------------------------------------

- copy the content of "data/translations" from the development machine to the production machine

For each translator in a each language:
- add/update the translator account, in "scripts" run "update_translator jsmith-at-mail.com fr"
  or get the translator account, in "scripts" run "show_translators jsmith"
- this returns the link to the translation page
  eg "http://micmap.org/php-by-example/fr/translation?email=jsmith-at-mail.com&translation_key=e4671dc35aad4210ad4195936c6fa83a"
- verify the link works
- email the link and the request to validate or fix translations to the translator

Note: the obfuscation of emails is not a security feature, it only prevents storing emails in the clear in the version control repository.


6. Validate translations
------------------------

The translators validate or fix translations with the interface and report back when they are done.

Note: the translators inputs (validations and changes) are stored in the "data/translations.production.log" directory on the production machine.


7. Update translations
----------------------

- remove the content of "data/translations.development.log" on the development machine
- copy the content of "data/translations.production.log" from the production machine to "data/translations.development.log" on the development machine
- update the translations with the translators inputs, in "scripts", run "update_translations *"
- run "check_translations" (again) which should report no issues if all translations have been validated
- copy the content of "data/translations" from the development machine to the production machine

Notes:
- there should be no "data/translations.production.log" directory on the development machine
- the "data/translations.development.log" directory might be present on the production machine but it is ignored on this machine
- the content of the "data/translations.development.log" is set not to be stored in the version control repository


PHP by Example
Copyright 2014 Michel Corne 
License   http://www.opensource.org/licenses/gpl-3.0.html GNU GPL v3