Setup:Translation Editor

From Cerb Wiki
(Redirected from Setup:Translations)
Jump to: navigation, search

Based on a 4.3.1 desk. Concepts and general instructions should still be valid. Needs new screenshots.

Understanding the language support in Cerb5

Cerb5 currently offers UTF-8 support for your international e-mail and has the infrastructure for translating the Helpdesk into your language of choice. Since we here at WGM only operate in English mode and don't plan to actually translate Cerb5 ourselves, we rely on the community to help us out. Here's our instructions for properly translating the Helpdesk using the built-in tools.

Translations are a Work in Progress

i.e. Not every string is ready to be translated.

One of the biggest unfinished sections you'll notice right away is 'helpdesk setup', and unfortunately there is no way to translate these pieces of text on your own through the interface. Since these leftover spots require preparation work on WGM's end, you'll have to wait to finish your full translation until we wrap things up.

Part of the reason it's not already done, is we tend to expend our limited development resources on more thought-provoking tasks and push back the monotonous "find & replace" coding that translation demands. That's not to say it's important to do other things first over something as fundamentally needed as translations, but it is often times put on hold in favor of other development opportunities.

At the same time we are not satisfied with a Helpdesk that's 80% finished with no early language packs to show for it. We should be rolling out more strings as development moves forward and can keep you up to date in a number of ways. The good news is you can start translating now, and continue to translate newly added strings without starting over.

Creating a new translation

To start the process you should update your Helpdesk to the latest stable build and enable ALL plugins (including the "Translation Editor") inside Cerb5; this ensures you get every available string that's translatable up front. Newer installs attempt to default to UTF-8 but if you did not create the proper database in the beginning, be sure to do so now and ensure the other language(s) work properly.

ALL plugins including the editor should be turned on, so all translation strings are exposed.
  • Click 'helpdesk setup', the 'Features & Plugins' tab and enable everything.
  • Click over to the new 'Translations' tab.

Selecting your new language

The interface might come off as a little confusing at first but it's actually fairly simple to use. You need to start by choosing the language you want to translate into.

Like the screenshot, we're going to assume you chose NOT to copy new text from a base language.
  • Click the 'Languages' button and select your language from the 'Add New Translation' drop down.
  • For the second drop down 'Copy New Text From' choose 'leave blank'.

Alternatively you could have specified a base language to copy new text from, but to make this tutorial more comprehensive and easier to follow we'll ignore that option. As the e.g. says normally this is useful for carrying over (or re-using) existing text from one language. For example, when translating to a British dialect that has a similar vocabulary to American English except for a few differences in spelling, you won't have to bother re-inputing the identical text.

If you HAD selected a base language, you would see the 'Translations' worklist had pre-filled all the text fields with the translated string. As you went through each string you would replace the pre-filled text field with something else, or leave it as is.

Note: Choosing 'English (United States)' as your base language gives you the default English translations that you currently see in the Helpdesk.

Tabbing through the Translations worklist

Observe the sidebar where 'Language = Spanish; Castilian (Mexico)' and 'My Translation = (blank)'; if the latter filter is not included go ahead and do so. That way when you save each block of text, the Helpdesk will filter out the saved translations and automatically move you forward to the remaining unfinished (blank) translations.

The (red or blue) boxed text is the English inside the Helpdesk you're going to be translating. Currently there are about 700 strings available for you to work on, but it's easy to translate text rapidly if you follow these recommended steps:

  • Starting at the top of the worklist, TAB-key through each text field, adding your translation for what you see in the boxed text.
  • In the screenshot, I'm translating my Helpdesk to Spanish and have changed the English 'Organization' to the Spanish 'Organización' and 'First Name' to 'Nombre'.
  • Once you get to the bottom of the list, click the 'Save Changes' button. This "resets" the worklist by clearing the translated text from the screen and showing the next batch of untranslated text.
  • Repeat the process again starting at the top until the list is empty.

Translate as much text as you feel comfortable with while feeling free to skip any text you need to. Any text field you leave blank will display a warning icon and default back to the original English in Cerb5.

Deploying your finished translation to your workers

After you've completed a suitable translation for your own internal use, to see your hard work you need to change the displayed language.

  • Click 'my account' in the upper right corner.
  • In the 'General' tab you'll see a 'Language' drop down. Change that to the new language translation and save changes.
Have the rest of your workers follow the same procedure the next time they login.

Sharing a translation

Once you've completed a translation to your language of choice (or did as much as you are capable of), you can then share it with other language speakers. We've made it as simple as possible to import/export any language or any combination of languages to a file you can upload to the web.

Exporting the translation to an XML file

Make sure you are filtering by the language you want to export in the search filter. Technically you could create a full language pack with several languages. But if you plan to share your translations to the general public, you definitely want to pick only one language so people can easily find and download that one language they need.

A Spanish translation file will look like cerb5_lang_es_MX.xml.
  • From the 'Add Filter' dialog, choose 'Language' > 'in list' > '(one) language', e.g. "Spanish; Castilian (Mexico)". If necessary, remove any other filters.
  • At the bottom of the Translations worklist next to the 'Save Changes' button, you'll see a second button called 'Export'. Click that and save the resulting XML file to your computer.

Sending your XML to WGM via e-mail

Feel free to e-mail with the XML file as an attachment. We'll take care of the rest.

Official Language Packs available to download

All language contributions are available in the install/extras/translations/ directory.

Importing an XML translation file

To install the language packs from GitHub into your existing Helpdesk, click the 'Import' button at the top and choose the XML file on your computer. If you want to add any custom translation you would do so the same way as before. Your local changes will override that language's default translation.

There's no need to change the language up front since the XML file already has the language code inside.

Updating your translation when new strings are ready

Updates include either adding new features in Cerb5 which create new English strings OR when we finish making existing English text translation-ready. We'll try to make it clear when more work on the translation infrastructure has been done via WGM announcements, either through the blog or forums.

  • Click the 'Synchronize' button. This finds any new English strings and copies them into your Translations worklist.
After we make an announcement on a fresh release with added translation support, update your Cerb5 build.

The window will show you a list of your translated languages and will ask how you want to integrate the new English text. As the footnote explains, it's best to set the drop down to 'leave blank' so you can easily search for "empty" text in your translations.

Find new strings.

Cerb5 should automatically set your new search filters to isolate the new untranslated strings. But you can double check to make sure 'My Translation = (blank)' and 'Language != English (United States)'.

Now translate just those new English strings and save your changes just like before. Remember this whole process is incremental and any syncs will keep all your previous translation work intact. If the changes were substantial you can go ahead and export the translation to share the updated output with the community.


  • I'm getting a mix of my language with new English text when I update the Helpdesk. What's wrong?

When you update to a new release with additional translation support, you will notice that any new strings of text default back to English. Unfortunately this way of doing things causes Cerb5 to have a mix of both languages, on the other hand this guarantees forward compatibility so the interface won't break. You can go ahead and use the "synchronize" method mentioned above to translate anything new.

  • I partially translated the Helpdesk already and want to import a more complete language pack. Will the imported language completely erase my local changes? Or can I keep my customized translations?

Yes, you can keep your customized translations and download a pack to translate the rest. Your local changes take precedence over any imported languages, the imported strings are set as the defaults and any customized text you had overrides them.

But if you want to let the imported language completely erase whatever changes you made, you can do that pretty easily. All you have to do is delete the language first and THEN import the new language.

Remove, save, re-add, save, import.
  • Just to be safe have all your workers go to 'my account' and change their language off of the one you are about to modify.
  • Then back in the 'helpdesk setup' 'Translations' tab, click the 'Languages' button and checkmark which saved languages you want to remove, save changes.
  • Re-open the "Languages" window and add a new translation in the drop down for that language, then do the import as usual.