Skip to content
This repository has been archived by the owner on Oct 22, 2020. It is now read-only.

Languages and Translations

Jump to bottom
Clément Habinshuti edited this page Jul 11, 2017 · 12 revisions

Languages and Translations

Contents:

Adding new languages to Casebox

Before translations for new languages can be added, you need to add the language to the Casebox configuration and.

You can register new languages globally by adding them as columns to the translations table and as entries in the config table of the main database cb__casebox.

Step 1: Add language column to translations table

The translations table is used to store text used in the main UI in different languages. New languages should also be added in the global translations table (cb__casebox.translations) even if you are not adding UI translations.

The translations table has, among others, a name column and column for each language, using the language's alpha-2 code as the name. Let's say our installation already has English and French, our table will have columns:

id,pid,name,en,fr,...

If we want to add the Spanish language, we add column es:

ALTER TABLE `translations` ADD `es` VARCHAR(250) AFTER `fr`;

Step 2: Add language to list of available languages

The languages available to Casebox are store in the value column of the config row with param='language' as comma-separated list of alpha-2 language codes:

SELECT value FROM `config` WHERE `param`='languages';

The result is something similar to en,fr

To add a language, simply append it's code to the comma separated string. For instance to add Spanish:

UPDATE `config` SET `value`= CONCAT(value, ',es') WHERE `param`='languages';

The new value would be en,fr,es.

Step 3: Add configuration for added language

Each language also has it's own row in the config table with param name language_$lg (where $lg is the alpha-2 code of the language).

The value of the config is as serialized JSON object used for localization:

{
  "name": "Spanish",
  "locale": "es_ES",
  "long_date_format": "%j %F %Y",
  "short_date_format": "%d.%m.%Y",
  "time_format": "%H:%i"
}

So to add configuration for the Spanish language:

INSERT INTO `config` (`param`, `value`) VALUES ('language_es',  
  '{"name":"Spanish","locale":"es_ES","long_date_format":"%j %F %Y","short_date_format":"%d.%m.%Y","time_format":"%H:%i"}');

Note: You can also add core-specific language config in the core's database config table using the same steps. Adding them to the config of the core will make the languages appear in the Languages drop down when the user is logged in.

Adding translations for the Casebox UI

Translations for the text used in the Casebox UI are stored in the translations table of the cb__casebox database (core-specific translations are in the similarly-named table in the core's database).

Each row has translations of the same text and each language has its own column. A script is used to import translations from a CSV file.

Make sure the languages are registered in the translations table before proceeding with the next step.

Step 1: Importing translations

The bin directory located in Casebox root, contains a PHP script called language_import.php. This is used to import translations for a new language from a csv file.

Usage:

php language_import.php <file> <language code> <column number>

where:

  • file is the path of the CSV to import,
  • language code is the alpha-2 code of the language, and
  • column number is the index of the column (counting from 1) for the specified language in the CSV file. This option, when not specified, 2 is used.

For instance to import French translations from the file located at ~/Document/translations.csv where translations for French are in the 4th column, we'd run:

php language_import.php ~/Documents/translations.csv fr 4

where the csv file would look like:

1,Auth,Authorization,Autorisation,
2,Username,Username,Nom d'utilisateur,
3,Password,Password,Mot de passe,
4,Login,Login,Login,
5,Reset,Reset,Réinitialiser,
...

Note:

  • Only the id column and the column of the language to translate are required in the csv file, other columns are ignored
  • The CSV file should not contain headers, language code and column are specified in the command inputs
  • If you want to import translations for multiple languages from the same file, the command should be repeated for each language, each time adjusting the column number input

Step 2: Update JS language files

Casebox also stores translations in JavaScript files in the httpsdocs/js/locale directory, these files are generated by the script bin/languages_update_js_files.php.

The script takes no parameters:

php languages_update_js_files.php

Run the script after importing translations in the global or core custom translations table.

Note: You can add core-specific custom translations by using the core's database in Step 1 and Step 2

Adding translations for arbitrary objects

This section complements the Multilingual section of the Dev docs on the official website. Follow the link to learn more about how Casebox handles objects translations.

Assuming you've already added the languages you want to translate to, Casebox provides a way to add translations for arbitrary objects created by the user and then display the correct version of the text depending the language the logged-in user has selected.

Step 1: Add field for each language to template

For each language you want to add translations for, you need to create a field called language_$lg (where $lg is the alpha-2 code of the language) on the template used to create the objects you want to translate (or the Templates template to make it part of all templates). Casebox creates dynamic Solr columns for these fields so you don't have to specify a solr_column_name (see the Dev docs link above for more info).

Once the fields are created, you can edit the objects you want to translate and populate values for the new title_$lg fields. If you need to translate a lot of objects at once, consider using the provided script following the instructions in Step 2.

Step 2: Importing translations from script

The bin directory contains a PHP script import_objects_translations.php that can be used to import translations for arbitrary objects from a CSV file. The script only works for objects of type object (such as Thesauri items, cases, etc.), basically any item in the core's objects table.

Usage:

php import_objects_translations.php -c <corename> -f <file>

where:

  • corename is the name of Casebox core to import the translations to, without the cb_ prefix
  • file the path of the CSV file to import

For example, to import the file ~/thesauri_translations.csv into the core named mycore, run:

php import_objects_translations.php -c mycore -f ~/thesauri_translations.csv

After running the script, you should reindex the solr core.

Format of CSV file

The first row of the CSV file should contain column headers, the first column is reserved for the ID's of the objects and can be called anything, the rest of the columns should be for the languages to translate, each named using the language's alpha-2 code. Each row after that should be for each object to translate. The ID's should match the ID of the objects in Casebox, they may optionally be prefixed with a hash # symbol.

Examples of valid CSV files:

ID,en,fr
1,Cheese,Fromage
2,Yes,Oui

or

object id,en,fr,de
#343,Dog,Chien,Hund
#542,Cat,Chat,Katze

Troubleshooting and FAQ

Can I use a different 2-character code from the official alpha-2 of the language?

Yes.

You can use a different 2-character code for the language you want to add. The code that you choose should be used consistently as the language identifier in the config table, as the column name in the translations table as well as in the commands and csv file inputs.

This can sometimes be a necessary resort for example when the official alpha-2 code of the language you want to add is already in use by another language or by another column in the translations table.

Examples:

  • If you have different translations for Mainland Mandarin Chinese and Taiwanese Mandarin (zh_CN and zh_TW), you can use a different code from tw on one of the languages.

  • Bahasa Indonesia has id as the official alpha-2 code, which is already used as the id column of the translations table, so a different code is necessary.

Can I use a language code of more than 2 characters?

No.

The language code used as identifier in configuration and translations must have exactly 2 characters.

I have added language entries in the languages param of the config table but I get errors when I run Casebox.

If a language is registered in config, whether global or core-specific, it must also be added as column in the cb__casebox.translations table. Otherwise DB errors will occur and the Casebox UI might not load.

I have imported new UI translations but I see no change on the UI.

Make sure to also generate the translations JS files using these steps. It is also possible that the browser is displaying old cached values, clear the browser data and reload the page to try again.

I have made errors in translations, how can I make corrections?

Update the CSV file with correct translations and run the appropriate commands again.

User Guide

For Developers

Clone this wiki locally