specs / translating
# Translating
## Document Status
This specification is a draft.
## Abstract
Translations must always be a community effort.
Resources in need of translation can be roughly divided into 2 groups. The first one being message strings (single strings), the other one being whole documents (i.e. narrative text). As most resources change with each new version it becomes necessary to update or add new translations with each new version.
### Status
The upcoming and current status of translation should be made transparent to all collaborators. This may happen in a public wiki document which gets edited.
### Workflow
1. Developers are working on a new version in `x-*` branches.
2. The integrator begins merging in branches into master, declaring string freeze 1 week before release. 
3. The integrator branches `x-translation` off of `master`.
4. The translation integrator extracts strings and updates existing message catalogs template and updates existing message catalogs.
5. The translation integrator assembles documents to be translated (i.e. generated API documents).
6. The translation integrator sends out resources to translation coordinators.
7. The translation coordinators work with translators in order to translate the resources.
8. The translation coordinators translate and send back resources until **2 days** before release.
9. The translation integrator commits the received translations to `x-translation`.
10. The translation integrator determines which locales are going to be supported on the basis of the completeness of received translations.
11. The integrator is notified that the `x-translation` is ready to be merged **1 day** before release.
12. The translation integrator sends out release blog post as early as possible (most often this is 1 day before release) to translation coordinators.
13. The translation coordinators translate and send back blog post as early as possible in order to have all translations ready on release.
14. The translation integrator adds the translations to the post as they are coming in (even after the release).
### Things In Need of Translation
- lithium_site static messages
- li3_bot static messages
- li3_docs static messages
- lithium generated API documents
- lithium release blog posts
- lithium press releases
- lithium guides
- lithium tutorials
- lithium welcome page on rad-dev.org
### String Freezes
String freezes exists so that translators have time to work on translations without worrying about that the original English strings in the source code change. After such a freeze the following changes must be announced to the translation integrator.
- Modification of a message which is marked for translation (with either `$t()` or `$tn()`).
- Marking a new message for translation (except there was already an identical one).