Version at: 09/03/2014, 19:52

# Adding a New Language to the Corpus (for Developers)

##Introduction

These are the instructions for adding a language to the Tatoeba corpus. Instructions for adding a language in which the Tatoeba UI will be displayed are found elsewhere.

These instructions were modified from [Assembla](https://www.assembla.com/spaces/tatoeba2/wiki/Adding_a_language_in_Tatoeba). **The sections from "In Your Local Tatoeba" onwards have not been updated yet.**

##FAQ for users
The FAQ for users who want to add a new language: [How to request a new language](http://tatoeba.org/eng/faq#new-language).

##Language icon
1. Create the icon for the language. The icon should be a PNG file of dimension 30x20. On each icon there is (in theory) a 1px line of color #dcdcdc on the border bottom and right. Most of the icons also have gone through a luminosity change, so that they are a bit more pale than the original image. Anyway, most of it doesn't matter right now. The most important is that the icon is a PNG file of dimension 30x20.

2. Commit the image to the repository. The icons are stored in the app/webroot/img/flags folder. Ask one of the people with repository access if you don't have it yourself and don't want to obtain it.

3. Update the app/webroot/img/flags directory on the server, to retrieve the new images for the new languages.

##Source code

There is a script that was used on the server to modify the right files to add the new language code to the appropriate files. As of 2014-03-02, an updated version of the [script](https://github.com/Tatoeba/tatoeba2/blob/master/docs/database/scripts/add_lang.sh) has been checked into our repository, though the script has not been uploaded to the server yet. The script takes the following parameters:

* three-letter ISO 639-code (e.g., "epo" for Esperanto")
* the English name of the language (e.g., "Esperanto")
* the ID of a list containing at least 5 sentences in the given language (to find the ID of the language, search the [list of lists](http://tatoeba.org/eng/sentences_lists/index) for the appropriate list, then roll over it with your mouse to see the URL, which contains the list ID)
* the string "dev" (on a development machine) or "prod" (on the server)
* the username for the database
* the password for the database
* the database name

Once this script is executed, the new languages will be available on the website. The sentences that were in the list with id <list_id> will have their language set to the new language (instead of being set to language unknown). This script edits the following files:

* **app/model/sentence.php**
Adds the language ISO code to the $validate array. Languages that are not part of this array are not allowed.

* **app/views/helpers/languages.php**
Adds the language ISO code and the name to the languagesArray() method.

* **docs/generate\_sphinx\_conf.php**
Adds the language ISO code and name to the $languages array. Also adds the ISO code to the $cjkLanguages array if the language uses Chinese, Japanese or Korean characters.

 
In the past, we used to edit this:

* **app/controllers/components/google\_language\_api.php**
Adds the corresponding case to the google2TatoebaCode() method, if Google supports the detection for the language. See the Language enum.

but now tatodetect takes care of language detection.

After you make your changes, commit your code to the repository, or have someone do it for you. See [Repositories](repositories).

##In your local Tatoeba

**This section has not been updated yet.**

* Connect to mysql and select the database.
* If you haven't done it yet, run the following script: 
 docs/database/scripts/add\_new\_language.sql. 
It will create a procedure to easily add a new language and do the necessary updates in the database.
* CALL add_new_language(iso\_code, list\_id, tag_name);
* Read the comments in add\_new\_language.sql to have examples of the procedure.
* Test that the language detection works (or can work) by adding a sentence with 'auto-detect'. There should be on Tatoeba a list of sentences in the language in question (named after the language in question).
* Test that you can change the language of a sentence into the language in question.
* Check that the count displays properly in the languages stats.
* If it's all fine, commit and refer to the ticket #225 in your comment (=> re #225) and indicate the languages that were added. Also refer to any separate tickets that were added to track adding these languages in particular. The syntax for referring to multiple tickets is described here. 

 
##On the dev

**This section has not been updated yet.**

* Go to the 'dev' repository.
* Update it, if necessary.
* Connect to the mysql database of the dev version.
* CALL add\_new\_language(iso_code, list_id, tag_name);
* Test the same things you have tested in local. 

 
##On the prod

**This section has not been updated yet.**

* If everything is fine with the dev, go to the 'prod' repository.
* htop
* Check that the load is below 2.
* Update the repository if necessary
* Connect to the mysql database of the prod version.
* CALL add\_new\_language(iso_code, list_id, tag_name);
* exit
* Check that the sentences that were in the list and tags have now the appropriate icon.
* Check that the language appears in the languages stats.
* cp /usr/local/etc/sphinx.conf /usr/local/etc/sphinx.conf.old
* php generate\_sphinx\_conf.php > /usr/local/etc/sphinx.conf
* Change the necessary things in the new config file (user, password, database and port). Look at the old conf file for reference.
* indexer --all --rotate & disown

##Historical information only
We used to follow this procedure for adding a new language (example: French):

* Create folder : /app/locale/fre/LC_MESSAGES
* Copy-paste default.pot into this folder
* Change it into default.po
* Open default.po with PoEdit (http://www.poedit.net/) and translate.
* Save. It will generate a *.mo file, which is used when replacing strings at runtime.

and when new strings were added:

* Follow the cake i18n instructions to generate the up-to-date POT file.
* Open the PO file (PO, not POT).
* In the menu : Catalog > Update from POT file…
* Choose the POT file that was newly generated

The language of the page is set through the URL.
Example: http://localhost/tatoeba2/fre/sentences/index

Resources:

* http://blog.jaysalvat.com/articles/choix-des-langues-par-url-dans-cakephp.php
* http://www.formation-cakephp.com/41/multilingue-18n-l10n

version at: 09/03/2014, 20:00

# Adding a New Language to the Corpus (for Developers)

##Introduction

These are the instructions for adding a language to the Tatoeba corpus. Instructions for adding a language in which the Tatoeba UI will be displayed are found elsewhere.

These instructions were modified from [Assembla](https://www.assembla.com/spaces/tatoeba2/wiki/Adding_a_language_in_Tatoeba). **The sections from "In Your Local Tatoeba" onwards have not been updated yet.**

##FAQ for users
The FAQ for users who want to add a new language: [How to request a new language](http://tatoeba.org/eng/faq#new-language).

##Language icon
1. Create the icon for the language. The icon should be a PNG file of dimension 30x20. On each icon there is (in theory) a 1px line of color #dcdcdc on the border bottom and right. Most of the icons also have gone through a luminosity change, so that they are a bit more pale than the original image. Anyway, most of it doesn't matter right now. The most important is that the icon is a PNG file of dimension 30x20.

2. Commit the image to the repository. The icons are stored in the app/webroot/img/flags folder. Ask one of the people with repository access if you don't have it yourself and don't want to obtain it.

3. Update the app/webroot/img/flags directory on the server, to retrieve the new images for the new languages.

##Source code

There is a script that was used on the server to modify the right files to add the new language code to the appropriate files. As of 2014-03-02, an updated version of the [script](https://github.com/Tatoeba/tatoeba2/blob/master/docs/database/scripts/add_lang.sh) has been checked into our repository, though the script has not been uploaded to the server yet. The script takes the following parameters:

* three-letter ISO 639-code (e.g., "epo" for Esperanto")
* the English name of the language (e.g., "Esperanto")
* the ID of a list containing at least 5 sentences in the given language (to find the ID of the language, search the [list of lists](http://tatoeba.org/eng/sentences_lists/index) for the appropriate list, then roll over it with your mouse to see the URL, which contains the list ID)
* the string "dev" (on a development machine) or "prod" (on the server)
* the username for the database
* the password for the database
* the database name

It should be executed from the directory in which the script is located.

Once this script is executed, the new languages will be available. You should execute it locally and verify that it works correctly. The sentences that were in the list with id <list_id> should have their language set to the new language (instead of being set to language unknown). This script edits the following files:

* **app/model/sentence.php**
Adds the language ISO code to the $validate array. Languages that are not part of this array are not allowed.

* **app/views/helpers/languages.php**
Adds the language ISO code and the name to the languagesArray() method.

* **docs/generate\_sphinx\_conf.php**
Adds the language ISO code and name to the $languages array. Also adds the ISO code to the $cjkLanguages array if the language uses Chinese, Japanese or Korean characters.

After you make your changes and test them according to the next section, commit your code to the repository, or have someone do it for you. See [Repositories](repositories).

##Tests
* Test that the language detection works (or can work) by adding a sentence with 'auto-detect'. There should be on Tatoeba a list of sentences in the language in question (named after the language in question).
* Test that you can change the language of a sentence into the language in question.
* Check that the count displays properly in the languages stats.
* If it's all fine, commit and refer to the ticket #225 in your comment (=> re #225) and indicate the languages that were added. Also refer to any separate tickets that were added to track adding these languages in particular. The syntax for referring to multiple tickets is described here. 
 
##On the server

* If everything is fine so far, go to the server.
* Execute "htop" to verify that the load is below 2.
* Update the repository if necessary
* Connect to the mysql database of the prod version.
* CALL add\_new\_language(iso_code, list_id, tag_name);
* exit
* Check that the sentences that were in the list and tags have now the appropriate icon.
* Check that the language appears in the languages stats.
* cp /usr/local/etc/sphinx.conf /usr/local/etc/sphinx.conf.old
* php generate\_sphinx\_conf.php > /usr/local/etc/sphinx.conf
* Change the necessary things in the new config file (user, password, database and port). Look at the old conf file for reference.
* indexer --all --rotate & disown

##Historical information only
We used to follow this procedure for adding a new language (example: French):

* Create folder : /app/locale/fre/LC_MESSAGES
* Copy-paste default.pot into this folder
* Change it into default.po
* Open default.po with PoEdit (http://www.poedit.net/) and translate.
* Save. It will generate a *.mo file, which is used when replacing strings at runtime.

and when new strings were added:

* Follow the cake i18n instructions to generate the up-to-date POT file.
* Open the PO file (PO, not POT).
* In the menu : Catalog > Update from POT file…
* Choose the POT file that was newly generated

The language of the page is set through the URL.
Example: http://localhost/tatoeba2/fre/sentences/index

###Language detection
In the past, we used to edit this:

* **app/controllers/components/google\_language\_api.php**
Adds the corresponding case to the google2TatoebaCode() method, if Google supports the detection for the language. See the Language enum.

but now tatodetect takes care of language detection.

Resources:

* http://blog.jaysalvat.com/articles/choix-des-langues-par-url-dans-cakephp.php
* http://www.formation-cakephp.com/41/multilingue-18n-l10n

Note

The lines in green are the lines that have been added in the new version. The lines in red are those that have been removed.