Internationalization and languages

TikiWiki is an international project, supporting many languages. The default interface language in Tiki is currently English/en. We support any language, which may be encoded and displayed using the utf-8 encoding. We are always looking for translators.

Tiki supports multiple languages and defines a mechanism to easily make the application available in other languages.

In the PHP scripts(.php files), all the text strings must be written as tra(“here goes the string�?); which calls the tra function that translates the string.
In Smarty templates (.tpl files), you should use the Smarty block, for example Hello world{/tr}.

This is how you write text in Tiki to be language-aware.

Once you have modified Tiki the get_strings.php script can be used to scan all the .php and .tpl files in the application regenerating/changing the language files. New strings are added to language files untranslated.

Creating a new language

1. Create a new directory under the “lang�? directory. Please name it using the standard RFC 1766:
   • 2-letter language code iso639 in lower case
   • eventually "-" and a 2-letter country code ISO3166 in upper case
     • For example, en = english, es = spanish,pt-BR = brazilian
     • Before Tiki1.8 only 2 lettter directories were possible
2. Give the adequate write permission to this directory (so that the web server can write).
3. If you are working on a Tiki stable release, copy the language file (language.php) from a language you are familiar with or from the en directory in your directory.
4. If you are working on a Tiki CVS version, run the script get_strings.php?lang=en as admin (change en with the 2-letter code of your language). This script collects all the strings of the Tiki code.
5. Edit/translate the language.php file.
   • Each text string looks like this:
     • "last modification" => "last modification",
       In Tiki1.8: some comments can be found after and the ligne can be commented (see below)
   • Leave the text on the left as it is and insert your new text on the right.
     • For example (in German),
     • "last modification" => "letzte Änderung",
       • Note that to get an umlaut over the A this German text uses the HTML code for an umlauted A: & A u m l ; .
     • In French, "last modification" => "dernière modification",
       • Note that the accents are utf-8 encoding
     • If you find some Smarty variables (ex:{$nb}) or some some php variables(ex:%s) leave then in both part
6. Tiki will automatically detect the new language once you save the language.php file.

Don't forget that the file needs to be in UTF-8 encoding to be displayed in Tiki. If you're using GNU Emacs to edit the translation, then you can choose the encoding with the command set-buffer-file-coding-system which is bound to 'C-x RET f' in the default setup.
A good editor choice can be also "gedit" (debian package too) that support UTF-8 encoding by default; or UniRed (GPL'd) for M$ Windows users. Another awesome Windows tool is WinMerge available from SourceForge (GPL'd too). To make it operate in UTF-8 mode by default - enter magic number 65001 in Edit->Options->Codepage. And finally there is SciTE - free source code editor for Win32 and X.

Translating as PO files

If you are more familiar with GNU Gettext's PO files, you may be interested to try out the PO convertor for TikiWiki. The converter makes it easier to keep your translations up to date.

Anyway, if you have ever translated PO files, you will know why it is good.

Updating a language file with the last Tiki code: get_strings.php

To update a language file (language.php), you have to run the script get_strings.php as admin. The script adds to the file the untranslated strings.

• To update all the languages files: get_strings.php
• To update only one language (ex: en) : get_strings.php?lang=en

Then you can edit / translate the new strings.

• With Tiki1.7 , some comments are added by get_strings.php at the end of a language.php file.
  • //perhaps not use : the string is no more found in the Tiki code by the script. Perhaps the string was really deleted, but perhaps the string is used through a variable , for example: $var{/tr}. As the string can still be usefull for a new translation, the line is kept . The translator can delete it. See the discussion about improving this point: UnusedWords
  • //First new line: all the strings from this line are new strings and are not translated
• With Tiki1.8_: //perhaps not use and //First new line have been replaced by 3 groups
  • //###start/end of unused strings
    The strings are not any more found in tiki : because they have been modified in tiki or because it is the value of a variable. Actually getstrings is not able to distinguish both cases. When you are updating the translation, it is better to keep these lines (they can help to find the close string) but at release time, this section msut be deleted (except for the variable values translation)
  • //###start/end of untranslated strings
    Each untranslated strings is preceded with "//". As soon as, you have translated, you need to take the "//", otherwise the next get_strings.php will delete your translation. The reason that they are commeted is that oterwise running get_strings.php twice woudl put untranslated strings in this section into the possibly untranslated strings section (not very fun if there are a lot of changes and the translated language has simmilarities with english and/or you don't translate a lot of cumputer terms).
  • //###start/end of possibly untranslated strings
    This section is just for checking. It is all the strings that have both part identical.

• With Tiki1.8 , you can use the option close that proposes you as a comment a string already translated 'close' to the new one. : get_strings.php?lang=en&close=1
  • //close "previously tranlated strings"=>"old translation". The algorithm used the levenshtein distance (the minimum letters number that differs)
• With Tiki1.8, you can use the option module. This option generates comments that describes in which .php and/or .tpl module(s) each string was found
• With Tiki1.8, you can use the option patch. This option looks for the file 'language.patch' in the same directory as the corresponding language.php and overrides any strings in language.php - good if a user does not agree with some translations or if only changes are sent to the maintaner
• With Tiki1.8, you can use the option comments. This option generate all comments (equal to close&module).
• With Tiki1.8, you can use the option spelling. This option generates a file spellcheck_me.txt that contains all the translated words (only once). You then have to use a traditional spellchecker (e.g. Open Office, Word or Emacs) on this file to find the errors and make the corrections in the original language.php. When running get_strings.php in spellcheck mode it is more convenient to not have the close and module options active (i.e. translate first and spellcheck later)
• With Tiki1.8, you can use the option groupwrite. This option makes the generated file langauge.php group writable, so that you can edit the file if you have group acces but not root acces. Just do not forget to run the script again without the parameter so that the write permission is reset.

• With Tiki1.8, the date and time formats can be translated in each language.php file. The admin settings will only overwrite the formats for the site language. 6 formats are added. The formats are explained in the strftime php manual :
  • long date format, %A %d of %B, %Y
  • short date format, %a %d of %b, %
  • long time format, %H:%M:%S %Z
  • short time format, %H:%M %Z
  • long date&time format, %A %d of %B, %Y[%H:%M:%S %Z]
  • short date&time format, %a %d of %b, %Y[%H:%M %Z]

Translation help

• It can be more easy to etablish a bilingual terminology before translating. A partial terminology can be found at TikiTermino.
• If you find some strings difficult to translate, please add your suggestions in LanguageEnglish
• Some useful tools:
  • wordreference

Please add your experience, comments here

Maintaining the translations between different tiki releases

A translator is supposed to work on Head until a pre-release is available (named RCxx). At this moment he is supposed to work on the CVS on this pre-release until a final release is available. The developpers are supposed to do a minimun change in the strings during this time. After the first release, the translator can go back to head.
Two tools are available to facilate the merge between the released version and the head version:

• doc/devtools/mergelang.pl (see the documentation in the file)
• get_strings.php?lang=xx& patch where the lang/xx/language.patch is the language.php of the release

Where to find a language file

All the language.php files are delivered with Tiki.

FAQ

CharacterEncodingTrouble

Utf8 and php string functions

The strings functions in php are not multibyte safe - and Tiki uses Utf8.
In Tiki1.7, the only way to have the strings working is to use the php multibyte support and to overload the string functions
In 1.7.2, Tiki supplies a limited mb_substr if this function doesn't exist . Some calls have been changed from substr to mb_substr - no functions are provided for the other string functions.

Right to Left Language

- Some wiki markers: {r2l},{l2r}, {rm}, {lm} can be used to change the text direction
- a css BiDi.css has been written for a right to left site.

Please follow the format convention described in TikiStringsFormatConvention
Some strings seems to be generated on the fly. Please read UnusedWords !

• In Smarty, the strings are between the tags string{/tr}:
  • The string can be on multiline.
  • The string can contain Smarty variables. Depending of the language file, the translation can occur before or after the variable substitution . For example :
    • {$value}{/tr}, and value=none or all. The string "{\$value}" will not be found in the language file, but "none"=>"aucun" and "all"=>"tous" will be found.
    • You will send {$nb} emails{/tr}. In the language file, you will find "You will send{\$nb} emails"=>"Vous recevrez {\$nb} emails"
    • if you know that a string will be translated later via a variable, please add the comment {*get_strings string{/tr} *} to have the string added to the language file. (tiki1.9)
  • Please enclose your into double quote to ease the translation with language using simple quote
• In PHP, the strings are the parameter of the function tra
  • the string can contain php variable
    • The string can be tra("Release %s"). In the language file, you will find "release %s"=>"version %s"
    • if you know that a string will be translated later via a variable, please add //get_strings tra("string") to have the string added to the language file.

(tiki1.9)

The translation phase in Smarty occurs at 2 moments

1. In a prefilter: it means when the Smarty cache is built. It means that the translation is not done each time you access a template but only once.
2. In a plugin : The string with variable or not find by the prefilter function is look again each time the template is accessed.

How to customize your language file

1) first way: the easy but slow one
At this end of the lang/your_language/language.php file (your_language will be replaced by en,fr, en-uk....)
Insert the following block just before ?>

include('lang/your_language/customization.php');
if (!empty($customizationLang))
$lang= array_merge($lang, $customizationLang);

Create the file lang/your_language/customization.php like this

<?php
$customizationLang=array(
"Online users"=>"My new translation"
);
?>

Don't forget that the customization.php file must be utf8 encoded
DOn't forget to clean the cache (admin-> System admin) to have the translation updated

2) second way:
Use the get_strings procedure. Create a file lang/your_language/language.patch (same format and encoding than above) and run get_strings.php?patch=y as an admin. Idem clear the cache

I18nDev
MultiLingualDev
UnusedWords