Translation Guide for LoxBerry

LoxBerry ships with a widget to translate LoxBerry and plugins to your language. Open the Translate widget to get your language to your (and all) LoxBerrys!

Translation and LoxBerry Update

Your translation is stored locally on your LoxBerry. LoxBerry Update or a Plugin Update will delete your translation. Therefore, if you are finished translating, download the file.

For system translation files it's possible to subscribe to the issue #666 at our bug tracker. You will be notified if the english system language file changes.

If you have a new translation or changes in an existing file, create a new issue and we will integrate your language into the LoxBerry and ship it with a LoxBerry Update.

For plugin translation files, contact the plugin author to integrate your language file to the plugin.

For Quick Starters, please see the major translation rules at the bottom.

System translation

Before you start translating LoxBerry, update your LoxBerry to the "Lastest Commit" to have the newest language files on your system. 

In the Translate widget, select your destination language. The list is grouped to European and international languages.

If you think that your language is missing, check the ISO 639-1 list at Wikipedia and drop us a message: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.

After you have entered your language code and hit "View", your language is loaded (or created, if it didn't exist).

Please be patient - it may take some time to load and process the language file.

Plugin translation

Before you start to translate a plugin, update the plugin to the newest version to have the current language files available on your system.

Plugin translations are only possible, if the plugin uses LoxBerry's template system for Perl and PHP. If the plugin does not use LoxBerry's language and translation system, you cannot select a translation file for the plugin.

The procedure is quite the same as for system translations:

Open the Translate widget and select "Plugin Translation" in the navigation bar.

If you select a plugin, the language file dropdown is reloaded to show you the translation files provided by the plugin. Usually there is only one file, but a plugin may provide multiple files.

Select a translation file, the destination language and hit "View" to load the selected language file.

Translating

Translation area

Translation files are organised in Sections. Sections are displayed as blue header.

The translation area has four columns:

  • The translation key: LoxBerrys templates uses keys and parses the keys to get your language phrase.
  • The source language: The English system text in LoxBerry
  • The destination language: This is your language.
  • The button row: To copy or revert changes.

Please keep in mind, that every change is saved immediately to your language file. There is no "Save" button. This is done in background to offer fluent work.

You can tab from field to field to enter your translations.

Colors

  • Intense yellow background signals an empty field.
  • White (transparent) background shows that this phrase is translated.
  • Light yellow background indicates, as a hint for you, that the source and destination language phase are identical (this may happen on some phrases, but normally not)

As saving is done in the background, it takes some seconds until the new state is displayed.

Buttons

  • Copy: Use it to copy the source phrase to your language. This can be useful if the source text is complicated and easier to translate inline.
  • Revert: Reverts the text to the state where the language was loaded. Remember, if you reload the language file with the "View" button at the top, this will get the new "old" state.

Download

If you have finished the translation, don't forget to download your translation file with the Download button at the top.

This is very important! As your translation is stored on your LoxBerry, an update will delete your language file. Therefore, download the file and create an issue at our GitHub issues tracker. We will implement the language to LoxBerry-Core and publish it with LoxBerry Update.

Translation rules

Because translation rulez! 8-)

We have summerized some rules to keep the translation files clean:

  • For system translation, update LoxBerry to the "Latest Commit". For plugin translations, update the plugin to the lastest version. Otherwise the language files would be outdated.
  • You can directly use your language's special characters. Our language files are stored in UTF-8 and directly support special characters.
  • If you see HTML tags in the source language, this is not an error. They are part of the translation. Use that tags acordingly for the translation.
  • Use the same punctiation characters as in the original language (e.g. colon, semicolon, period, … , or possibly nothing)
  • Do not translate proper names (names of Plugins, brands, common names,…)
    • LoxBerry is written LoxBerry; or, in English, multiple LoxBerrys (without apostrophe), or one of LoxBerry's settings (belongs to LoxBerry, therefore with apostrophe). Keep "LoxBerry" accordingly in your language.
    • "LoxBerry Update" is called "LoxBerry Update" in every language
    • Widgets (the "plugins" on the system settings page) are always called "Widget" or widget
    • This widget, "Translate", is called "Translate" in every language.
  • Be careful on technical terms to use proper translation, or possibly keep the common English terms. 
  • Keep the capitalization of words. Especially buttons always start the first letter of the first word uppercase.
  • If the English terms of the update types “Release” and “Pre-Release” are commonly known in your language, keep them, as these are terms we have borrowed from GitHub.
  • The Donation page:
    • We ship with an international link to "Doctors without borders" to offer donations from every country.
    • In the link and linktext keys, feel free to add your national link to your countries "Doctors without borders" website. But please, also keep the international link.
  • Do not add any additional text that is not present in the source text, and do not insert additional HTML tags as the may break the layout.
  • If you see red error message below the input fields:
    • Source language: Drop us a message at GitHub issues, or in LoxForum. We have to correct the error.
    • Destination language: The Translate widget may warn you about strange things in your translation. Please enter the input field, check the translation and leave the input field. The phrase will be saved fixed (but the warning won't disappear until reload).

Please don't forget to download the translation file and submit it! 

Older plugins

Older plugins will use the newly created or updated language as well. LoxBerry uses co-called "legacy" templates to present the LoxBerry 0.2.3 formatted templates to older plugins.

The generation of these templates usually is triggered automatically, but not with the Translate widget (it would generate heavy disk writes for every phrase). Therefore, to trigger the generation of the legacy templates, go to My LoxBerry, change the LoxBerry name (and change it back). The legacy templates will be updated. Alternatively you can reboot your LoxBerry.

Language testing

You have two options to test your newly created language:

  1. Go to "My LoxBerry" and switch the language. The language is saved as system language.
  2. Add &lang=de (your ISO code) to the URI. This is not persistent, but only for the current page.

Language fallback

LoxBerry has a fallback mechanism to display phrases in English, if the phrase is missing in your language. If your translation is incomplete, you'll have a language mix-up of your language and English.

Plugin Authors

  • Use the template and multilingual system from LoxBerry:
  • Keep in mind, that the source language is fixed to English.
  • The Translate widget never touches the English source language file.
  • The Translate widget does not sync source and destination - Keys with phrases in the destination, that do not exist in the source, will be lost.
  • Translate may warn you in the UI about "strange" things or errors in your source file - correct them directly in the source file.
  • Use sections in your language file.
  • If translations already exist, and you completely change the content of a phrase, translators won't take notice about. Therefore: Change or clear the translations yourself, or change the key. Changing the key will lead to an empty destination phrase and the template system will fall back to English.
  • If your plugin currently use German as the main language, you can try this "hack" to translate from German to English.