i18n - 3. Procedure for Updating Documents

Since the English documentation is the baseline, it must be updated first. Such an update may come from a member of the i18n team (e.g. the English Documentarians) or directly from the core developers.

In order that things go smoothly, the following procedures should be followed:

3.1 Call to Translate

If a new document is posted, or changes are made in the English documentation, a message should be posted to the fink-18n list informing all translators of the fact. The message will contain the following:

A note in the subject line indicating that this is a request for translation, e.g. "[translation]", or "[translation-delayed]" for items where the English documentation is going online with a delay.
In addition, the filename of the base file should be included somewhere in the message.
A full diff, e.g.:
```
diff -Nru3 -rlast_revision rhead 
```
to show the modifications in context.

Note: since committing the XML file automatically produces a message on fink-commits that meets all of these criteria, an easy thing to do is to forward such a message and re-title the subject. However, this will fail if many changes were made.

3.2 New Document

The English version of the document is committed and activated, and it is translated as below.

Note: When the new document is inside a new directory, you shoould add that new directory to the Makefile located in the xml directory. Otherwise the built process will not complete successfully.

3.3 New Translations

The language team leader (or someone else with CVS access) will commit and activate each document as it becomes ready.

This classification includes:

The first time a translation is made of an existing document.
Partial translations of an existing document.
Translation of a new English document

3.4 Prompt Update to Existing Documentation

The base English documentation is committed and activated immediately--whomever changed the XML should commit the HTML and PHP, and do the activation. The translation teams then update their versions, commit all of the files (XML and PHP), then activate the changes.

Never change a dynamically generated php file; change the xml file instead.

Check that the cvsid line near the beginning of an xml file is not splitted.

Notes:

Changes to the Internationalization HOWTO (this document) will always be made on this schedule, because such changes affect all translation teams.
Changes to the static documents (PHP files not generated from XML) will always be made on this schedule as well, because it's hard to delay their activation.

3.5 Delayed Update to Existing Documentation (XML-generated files only)

In this case, the English version of the XML file is committed, but not the PHP and HTML files, i.e. stop after step 5 under of Dynamic under 2.9. All translators do their work and commit only their XML file (i.e. the same as for English) within an agreed-upon timeframe. All of the PHP and HTML files will be generated, committed, and activated simultaneously at an agreed-upon time by one person, e.g. someone from the i18n core team.

3.6 For Developers and English Language Documenters

The current policy is that all documents should be updated according to the prompt update schedule, unless you have a specific reason to do otherwise.

Next: 4. Additional Resources