Centova Cast v3 Localization

Question:

How can I translate Centova Cast v3 into another language?

Answer:

Centova Cast may already support your preferred language. To enable one of Centova Cast's bundled language packs, please refer to the Changing Languages article instead.

Creating a New Locale

Perform the following steps to create a new Centova Cast locale:

  1. Create a new directory under /usr/local/centovacast/system/i18n/locale/ to contain your new locale. The directory name should match the name of your locale; for example, if you're translating to German, you might use /usr/local/centovacast/system/i18n/locale/de_DE/.

  2. Copy the template localization files from /usr/local/centovacast/system/i18n/locale/template/ into the directory you created in step 1. These template files contain all of the English-language strings that need to be converted into your target language.

  3. Translate the .po files in your new locale directory; methods for doing so are explained in detail in the next section.

  4. Edit your new language file and enter translations for all of the English strings. This is explained in detail in the next section.

  5. Rebuild Centova Cast's language database by running: /usr/local/centovacast/sbin/updatelanguages

  6. Restart Centova Cast to apply the changes: /etc/init.d/centovacast restart

The new language should now be installed in Centova Cast, and may be enabled as described in the Changing Languages article.

Editing your Locale Files

Centova Cast's localization system uses the standard GNU Gettext .po file format, which is the standard for localization under Linux. Locale files in .po format can be edited by hand with any Unicode-compatible text editor, or using specialized localization editor such as Poedit (the recommended approach).

Editing Locale Files with Poedit

To begin editing your Centova Cast localization files using Poedit, copy the localization files (*.po) to your computer and launch Poedit.

Translating the locale files

To translate a locale file:

  1. Click Open.
  2. Navigate to the directory in which you saved the .po files.
  3. Choose one of the .po files to open. (The purpose of each .po file is described in the Locale File Names section below.) Select a .po file and click Open to open it in Poedit.
  4. Use the Poedit user interface to translate your strings.
  5. Click Save to save your translation.

Repeat this process for each of the .po files until you have translated them all.

The Poedit user interface

The Poedit user interface is divided into four sections.

  1. Strings list
    The topmost, largest pane contains the list of strings to translate. These are sorted alphabetically, with strings that still need to be translated at the top (and already-translated strings at the bottom). Click on any of the strings to load its information into the other three panes.

  2. Source text
    The source text field appears immediately below the strings pane, and contains the full, English text of the string to be translated. Some strings may include placeholders; see String placeholders below for details on how to use and preserve them.

  3. Translation
    The translation field appears immediately below the source text pane, and contains the target-language translation for the English string displayed in the Source text pane. If the string has not yet been translated, this is where you will enter your translation.

  4. Notes for translators
    The notes for translators field appears to the right of the source text and translation fields, and contains tips that may be useful for you in identifying the purpose or meaning of the source text. In Centova Cast localization files, we use this field to provide information about where in Centova Cast the string is used, and in what context.

Editing Locale Files with a Text Editor

While we do not recommend using a text editor to edit .po files (a purpose-built editor such as Poedit will always yield more reliable results and avoid corrupting the language files), it is possible to do so if you do not have a locale editor available.

In brief, a .po file is composed of a series of msgid entries representing the English-language strings to translate, and msgstr entries representing the translations of the strings in the target language. These are accompanied by comments (beginning with # characters) providing contextual information to aid in identifying the purpose or meaning of the English string.

For example, a single entry in a .po file might look like:

#. File www/system/templates/admin_settings.tpl:81
#. Context: <tr>
#.              <td>{="SMTP password"}:</td>
#.              <td><input type="password" name="settings[smtppass]" value="{$settings.smtppass}" size="15" maxlength="128" /></td>
#.
#: www/system/templates/admin_settings.tpl:81
msgid "SMTP password"
msgstr ""

In the above example, we see the following:

  1. Several lines of contextual information in comments (preceded by # characters) which demonstrate how and where the text is used in the Centova Cast interface. In this case, the text is used in an HTML template file named admin_settings.tpl, and is clearly used as a label for an input field.
  2. A msgid line identifying the English-language string as SMTP password. This is the English text that we need to translate.
  3. A msgstr line, which is where we need to fill in the translated text in our target language.

To complete the translation of this example entry into (for example) German, we would change the msgstr line to:

msgstr "SMTP-Passwort"

It is important to note that you must not change the msgid line -- the msgid line must remain in English. Place your translation on the msgstr line instead.

String placeholders

Some strings in the locale files may contain placeholders such as %s or %0.2f. These are used by Centova Cast to insert data into the string at runtime. For example, in a string such as:

Total: %s MB

...the %s placeholder might be used to insert the number of megabytes to be displayed in the user interface.

It is essential that you preserve all such placeholders in your translated strings. For example, a German translation of the above string might look like:

Gesamt: %s MB

You may move the placeholder as necessary such that it makes sense in your target language; for example, the English string:

Could not write to %s

...could be translated to German as:

Konnte nicht auf %s schreiben

The only requirement for placeholders is that the exact placeholder from the English string must appear in the translated string; its location in the string doesn't matter.

Locale File Names

Centova Cast's uses a substantial number of text strings throughout its client, reseller, and administrator areas, as well as throughout the rest of the web interface, and performing a complete translation may require a significant investment of time. Many strings are never seen by a client, however, and as such they may be of a lower priority when performing a translation.

To assist the translator in identifying the strings of greatest importance during a translation, the localization system separates the strings into the following individual files:

  • external.po - includes all strings accessible to the public prior to logging in
  • user.po - includes all strings accessible to clients after logging in
  • common.po - includes all strings from common areas of the web interface (accessible to clients, resellers, and admin)
  • admin.po - includes all strings from the administrative interface (accessible only to the admin account)
  • error.po - includes error message strings
  • messages.po - includes status messages and log strings that are rarely seen by users
  • util.po - includes utility strings, mostly used by the Centova Cast installer
  • billing.po - includes billing-related translation strings

Note that by design, some strings are used in multiple places throughout the web interface. Regardless of how many places a strings is used, it will only appear once in the localization files, and will always be included in the most public of the above localization files. So for example, if a string happens to appear both in the administrative interface and in the client interface, it will be included in user.po, not admin.po.

Troubleshooting

I made changes to the language text but they did not show up in Centova Cast. Why?

Most likely you either forgot to run updatelanguages or you failed to restart Centova Cast. Remember that after making changes to the language files, you must run the following two commands before they will appear in the Centova Cast web interface:

/usr/local/centovacast/sbin/updatelanguages
/etc/init.d/centovacast restart

After running these commands your changes should appear in Centova Cast.

My locale does not use a 12-hour date format. Can I customize this?

Yes. Refer to the _DATEFORMAT, _TIMEFORMAT, _NODAYFORMAT, and _NOYEARFORMAT strings in common.po, which allow you to change the way dates and times are represented in Centova Cast when your locale is active.

My language uses extended (non-ASCII) characters, and they're showing up incorrectly.

Ideally, you should be using Poedit to edit your localization files; Poedit will automatically ensure that any special characters show up correctly.

If you absolutely must use a text editor, however, then you must ensure that your text editor is UTF-8 capable. Centova Cast internally operates exclusively in UTF-8 to ensure support for all possible languages and character sets. The locale file should be saved with UTF-8 encoding in order for the special characters to be preserved. (Hint: Microsoft Notepad is not UTF-8 capable.)

Notepad++ is an example of one such editor, and it is free and open-source. For UTF-8 mode in Notepad++, click Format->Convert to UTF-8 without BOM.