Custom translations

Modified on Mon, 12 Aug 2019 at 02:08 PM

The Omniscope user interface can be translated into any language, with the language "dictionary" being a data file that you can edit, in order to improve, complete and extend the available languages and translation dictionaries in your local installation. We welcome feedback regarding existing translations, and any contributed translations will be added to the app for everyone to use.

We offer each translator a free rolling 3-month Omniscope Classic Desktop + Evo Pro hybrid license key, for translating and maintaining translations going forward for the latest rock build, for each language. If you would like to participate in our Translators Programme, please contact us.

Translating Omniscope Classic

For Omniscope Classic, we support a number of common languages out of the box. See the Translation Guide in our previous knowledge base, for how to edit and contribute language data.

Translating Omniscope Evo

For Omniscope Evo, user interface translation and custom translations are available in version 2019.3, with additional language translations under way. Here's how it works.

An introduction to the language settings dialog

A flag appears at the foot of the welcome page (files list), and in the "3 dots" menu top-right of the Workflow and Report apps. It shows the current language and country variant setting (here, English/UK):

The language of your system will be chosen by default, if the Omniscope has a sufficient level of translations for that language. At time of writing, Omniscope Evo does not have any complete translations, but this will soon change.

Click the flag to change your language settings. This setting only affects your browser; other users are unaffected:

You can pick from available languages. The % complete shows how much of the translation is complete for the given language in the enclosing app; this may be different for the Welcome, Workflow and Report apps:

After changing language and clicking Apply, your browser will refresh to immediately reflect the new language. However:

Some phrases will not be translated yet; these will remain in English
Some on-screen text will not be "translatable"; this is either intentional (e.g. values in your data, or non-translatable acronyms or names such as "Sankey") or an omission on our part; if the latter, please let us know.

There will also be a setting in the Admin app to change the "server installation language"; this is not covered here.

Finally, the "Custom translation" section provides some instructions, tools and options to develop a custom translation for Omniscope (read on for further instructions):

The language translation process

Omniscope Evo supports custom translations. This allows a network of translators to contribute translations and test them directly. It allows the community to submit improvements. And it allows a production installation of Omniscope Evo to support new languages before Visokio have completed verification and inclusion.

Update: The best way to edit languages is using Omniscope Classic and an IOK file. Follow steps in this brief guide; skip over these steps and continue reading from 'The languages data file format' below.

The process for custom translations in Omniscope Evo is as follows. Follow these steps if you don't have Omniscope Classic:

Setup: Install Omniscope Evo.
Open the language settings dialog and expand the "Custom translation" section (as above).
Click "Download language data". A "languages.csv" file will download.
Place the file in your "omniscope-server" file, as directed in the dialog. This will allow you to preview the effect of your translations, immediately. Just a browser refresh is required - you do not need to restart Omniscope Evo.
Editing and previewing: Use a spreadsheet such as Excel to edit this file. Populate empty cells and correct existing cells, in the language columns such as "fr" and "fr_CA". See below for details of the file structure. Some things to be aware of:
1. We use "=" in cell to indicate "same as English"; this can cause problems with some spreadsheet software (if you see "#ERROR!" you're running into this).
2. Also take care with 'True' and 'False' values which must not get converted to "TRUE" and "FALSE".
3. If using Omniscope to edit the CSV file, be sure to disable "Auto-convert to empty" (Classic) or "Convert usual placeholders to null" (Evo) when opening the CSV.
4. Be sure to import/export the CSV using "UTF-8" charset (this is not the default on Windows).
Once you've saved some edits to the CSV file, it's time to preview them. In Omniscope Evo, refresh the browser (F5 or Cmd+R). Open the language settings dialog again, and change to the language you're editing and Apply, if not already selected. Your edited phrases should now appear in the Omniscope Evo user interface. You can also use the "Diagnostic mode" in the same dialog to highlight missing or all translatable phrases in the UI.
Repeat the previous two steps as needed.
Sending us the work: Send the "languages.csv" file (with your edits within it) to support@visokio.com. Give us an overview of what rows have been updated; be sure to describe exactly which columns you've edited.
We'll check your edits are structually valid, and incorporate the text into Omniscope Evo. A new build will be made available shortly. Meanwhile make no further edits to the local languages.csv file.
Replacing and checking the build: Once a build with your edits is available, install it.
Remove "languages.csv" from the "omniscope-server" folder (but keep a backup in case something went wrong). This will revert Omniscope Evo to using the (hopefully updated) bundled translations.
Refresh the browser and check your edits are present in the Omniscope Evo user interface.
Now go back to step 2 if you wish to do another round of further translations.

Note that, if sent a CSV file, of course you can work on translations without any of the above steps, and send us the CSV back, but it's helpful to see your work come to life in Omniscope Evo itself, and it allows you to check phrases in context, and identify missing phrases to prioritise first.

The languages data file format

This is a UTF-8 encoded CSV file and can be edited by Excel or other proper CSV compliant editor. If you have an Omniscope Classic license, this is probably the best tool to edit translations, although you should use the Classic 'editedLanguages.iok' approach covered by the classic Translation Guide. Whatever editor you use must support and preserve UTF-8 encoding, and Excel-style cell quoting and escaping.

The set of columns in this file is large and might be quite daunting:

En,Count,Context,Location keywords,Date phrase introduced,Visibility,Guidance,en_GB,en_GB status,en_US,en_US status,Ar,Ar Status,ar_SA,ar_SA status,De,De Status,de_DE,de_DE status,Es,Es Status,Es_Es,Es_Es Status,Fr,Fr Status,Fr_Fr,Fr_Fr Status,It,It Status,it_IT,it_IT status,Ja,Ja Status,ja_JP,ja_JP status,Ko,Ko Status,ko_KR,ko_KR status,Nl,Nl Status,nl_NL,nl_NL status,Pl,Pl Status,pl_PL,pl_PL status,Pt,Pt Status,pt_BR,pt_BR status,Ru,Ru Status,ru_RU,ru_RU status,Th,Th Status,th_TH,th_TH status,Tr,Tr Status,tr_TR,tr_TR status,Zh,Zh Status,zh_CN,zh_CN status,zh_TW,zh_TW status

However this breaks down into only a few significant primary columns, and many per-language and per-language-and-country columns. Language and country variants are mainly identified using ISO 2-letter codes, e.g. "Fr" for French, and "fr_CA" for the Canadian variant of French (we don't currently have that variant, mind).

Primary columns:

En - the English (UK) phrase. This is also the unique identifier. See "Phrase format" below for more detail on what this can comprise, but most commonly this is just a phrase of text needing translation. Case-sensitive (although see 'Fallback', below). Don't edit this. Let us know if you see errors in this field.
Count - the number of times the phrase occurs (this is somewhat meaningless as it refers to occurrences in our codebase, rather than how often it appears in the interface). A very rough indication of how common the phrase is. Don't edit this.
Context - a comma-separated list of categories for where the phrase occurs - used internally and also for your benefit. For example "server" means it appears in the Classic app and the server-side Evo app. Whereas "client:Welcome" means it appears in the Omniscope Evo Welcome front-end app (the file list page). Use this to skip phrases that don't appear in the web apps, for example. Don't edit this.
Location keywords - a space-separated list of keywords derived automatically from where in the Omniscope Evo codebase the phrase occurs. This can be used to give you some idea of the contextual meaning of the phrase. Don't edit this.
Date phrase introduced - a machine-generated date, from when this phrase was first added to Omniscope and made translatable. Don't edit this.
Visibility - a category of how prominent the phrase is, "Highest" being the most prominent / the first phrases that are needed (within a given 'Context'). Manually populated to a partial level; may not be up to date. You can edit this to improve the file, but let us know if so when sending us your edits.
Guidance - a manually edited explanation of the phrase or its contextual meaning. Rarely used. You can edit this to improve the file, but let us know if so when sending us your edits.

You may wish to sort or filter the data in various ways to prioritise translation work, e.g.:

By Context then Location keywords to roughly group related phrases together;
By Visibility to see very roughly prioritised "High" and "Highest" phrases first;
By Count to see the approximately more common shorter phrases and translate these first;
By Date phrase introduced to prioritise more recent developments.

Per-language columns:

These are based on the 2-letter ISO 639-1 language code (not counting "En" which is non-editable and mentioned above). Note, although language codes are lowercase, in this file we have case-insensitive column names, and the case varies due to auto-capitalisation behaviour in Omniscope:

The language translation column, e.g. "It", containing the base language translations for Italian. Typically this will be, by far, the most populated of (e.g.) Italian columns, and typically will contain the Italian (as spoken in Italy) variant itself. Edit this column, as described below..
A corresponding status column, e.g. "It Status". A free-text rarely used respective column containing arbitrary markers corresponding to "It" entries that need checking or questioning, e.g. "check" or "this is wrong". Some older phrases may have status values indicating machine translation was used; we experimented with this in the past as a starting point for translators; remove this if you have verified the translation. Edit this column if needed to help manage translations.

Per-language-and-country columns

These are based on the 2-letter ISO 639-1 language code, a "_" separator, and the 2-letter ISO 3166 country variant code:

The language translation regional customisation column, e.g. "it_IT" or "it_CH", typically mostly empty, containing the country-specific variations where they differ to the value in the base language-only column (e.g. "It"). Omniscope will pick this value in precedence, but if empty, the language-only value will be used.
A corresponding status column, e.g. "it_CH status". See equivalent notes above.

Typically "it_IT" is completely empty because "It" already contains all Italian-as-spoken-in-Italy translations.

Whereas "it_CH" (should we have such a variant) would be populated for those rows needing a customisation for how the Italian-speaking Swiss regions tend to deviate from how Italian is spoken in Italy. Typically, regional variants are are few, so such "non-mother-region" language variant columns are mostly blank.

For a language to be available in Omniscope, there must be both a base language (e.g. "It") and at least one country variant (e.g. "it_IT"), even if the country variant columns are completely empty.

Special cases

Chinese: this is uniquely different; "zh" is an empty field. Simplified Chinese is in "zh_CN" and Traditional Chinese in "zh_TW". While this normally means "Chinese as written in Mainland China" or "Chinese as written in Taiwan" respectively, this is used in Omniscope to mean generic Simplified Chinese and generic Traditional Chinese.

English: this implicitly has a non-editable "En" field because it's the unique key in the file (see above). Still, we also have "en_GB" and "en_US" columns, providing region-specific customisation of the non-editable "En" column. You can also edit these, e.g. to reflect the spelling of "colour" vs "color".

Adding a new language or country variant

Let's say we wanted to add support for the Malay language (language code ms), and that the 'mother region' might in this case be Malasia (country code MY), and we wanted one language choice for this language "Malay (Malaysia)" for any Malay speaker to pick (whether they are in Malaysia, Brunei or Singapore, etc.):

Add the base language column, named according to the 2-letter ISO 639-1 code, in this case "ms". Thus your column should be "Ms".
Add the country variant column, named according to the 2-letter ISO 3166 country code, in this case "MY". Thus your column should be "ms_MY".
Populate the "Ms" column with Standard Malay translations.
Leave the "ms_MY" column blank, but it must exist.

Let's say we wanted then to add support for the Brunei variant of Malay (country code BN), giving two choices "Malay (Malaysia)" and "Malay (Brunei)":

We already have the base language column "Ms" containing standard Malay. This will provide the bulk of translations.
Add the country variant column, in this case "BN". Thus your column should be "ms_BN".
Look in the "Ms" column for Standard Malay translations which are not appropriate for Brunei. Populate the "ms_BN" column with the Brunei variant only for such rows.

Example row data

A typical row in the file might look like this (omitting some columns):

En: Print
Context: server,client:Report,client:LegacyReport
Count: 6
Location keywords: App Backend Button Buttons Com Data Definition Explorer Impex Java Js Menu Method Mobile Print Printing Publisher Report Screenshots Service Src Tabscreenshots Toolbar Ui Web
Date phrase introduced: 08-Oct-2010 21:56:48
Visibility: Highest
Guidance: (blank)
De: Drucken
De Status: (blank)
de_DE: (blank)
de_DE status: (blank)
Fr: Imprimer
Fr Status: (blank)
fr_FR: (blank)
fr_FR status: (blank)
Ru: Печатать
Ru Status: (blank)
en_GB: (blank)
en_US: (blank)

Phrase structure

A value in English in the "En" column, and its corresponding translation in a language column (e.g. "Fr"), are most commonly plain text words, sentences or paragraphs:

Print
Imprimer
Please enter the password to open this file
Veuillez saisir le mot de passe pour ouvrir ce fichier
You have cancelled mid-calculation. Values in formula fields may now be incorrect or inconsistent.
Vous avez annulé mi-calcul. Il se peut que les valeurs dans les champs de formules soient maintenant incorrectes ou incohérentes.

It is case-sensitive (although see 'Fallback' section below); be sure to preserve equivalent capitalisation and lowercase styles in the translated text, unless the target language has different rules.

It can also contain line breaks and wholly blank lines; be sure to enlarge e.g. Excel row height, so you don't miss parts of the phrase:

No sets selected.

Choose sets using the Sets picker.
Aucun ensemble sélectionné.

Choisir des ensembles en utilisant le sélecteur d'ensembles.

In some specialist cases it might contain HTML tags or markdown format text; these should be preserved in the translation.

Parameters and other non-translatable markers

TL;DR: You will often see curly brackets such as {2} or {2, name} or {Something} or {~verb}. You will occasionally see HTML tags such as   in older phrases.

Although these can be simplified and sometimes removed (read on), the safest bet is to preserve them exactly, somewhere in the translated text, and do not translate anything inside curly brackets {} or angle brackets <>.

Where a parameter needs to be injected dynamically into the translation, we use "{n}" where n is a parameter index (a number starting from zero). You must preserve the parameters in the translation, but the order can change if the language mandates that.

Error with result for record {0}
Erreur de résultat pour l'enregistrement {0}
For example, this might be displayed as: Erreur de résultat pour l'enregistrement 53
Apply settings to all {0} views
Appliquer configurations à toutes les vues {0}
between {0} and {1} (inclusive)
entre {0} et {1} (inclus)
For example, this might be displayed as: entre 5 et 10 (inclus)
The cell at {0}:{1} contains the formula "{2}." This formula could not be evaluated and was ignored.
La cellule {0}:{1} contient la formule "{2}." Cette formule n'a pas pu être évaluée et a été ignorée.

Parameters sometimes have a comment explaining their meaning, with the parameter always taking the format {n, m} where n is the parameter index as above, and m is a free text explanation of what the parameter represents, written by us:

{0, accept} all tables that match {1, all} of these rules
{0, accept} tous les tableaux qui correspondent à {1, all} de ces règles
Here it's ok to drop the comment in the translation, as long as the parameter index is still present: {0} tous les tableaux qui correspondent à {1} de ces règles

If you see {~some text}, i.e. curly braces always beginning ~, it is a clarification of the phrase meaning. Such text will be stripped before it is displayed, and can be freely omitted from the translated text, but it allows you to distinguish between e.g. a noun and a verb, where English doesn't distinguish. For example:

run
courir (perhaps you have to guess here - let us know if so)
run{~verb}
courir
run{~noun}
course

You may see some classic / server-only phrases containing e.g. "{Something}" which means the text is passed-through and perhaps separately translated. You must copy this text into the translated text, without editing what's between the { and }. However we don't currently use this in web-facing text in Omniscope Evo.

Entire translated cell placeholders

In a translated language or country variant column, the following special values are supported, instead of proper translations. In these cases only can the parameters/markers above be omitted. The cell must match this exactly:

An entirely blank cell, meaning missing translation;
The single character "=", meaning "same as English". Use this to indicate a phrase which does not need translation at all. For example "Table" in English is also "Table" in French; write "=" to mean it's the same, rather than copying the value, or leaving blank which would imply a missing translation.
The single character "?", meaning "I don't understand". Omniscope will treat this the same as a blank cell, but it can be used as a marker to ask for help/guidance when sending a file back to us.

Fallback and precedence

When Omniscope needs to translate a phrase, it applies the following logic, which will help you to understand what's happening and perhaps to optimise your translation work.

Let's say you're in the "fr_CA" locale and Omniscope has near-complete translations for fr, fr_CA and fr_FR. Omniscope will therefore auto-select "fr_CA" as a valid translation, without having to explicitly configure it in the Language Settings.

First, Omniscope composes the phrases for your locale. Since you're using "fr_CA", we take this column and superimpose it on top of the "Fr" column, such that we now have a single column containing all translations into French, prioritising the Canadian variant where relevant.

(If you were in fr_CH and we didn't have such a variant in the file, Omnsicope would automatically assume it was fr_FR, the "mother region" of the French language.)

Then Omniscope looks for a populated translation. The languages.csv file should contain rows for all distinct phrases, but if a language has incomplete translations, Omniscope will look for looser matches to improve the user experience when missing exact translations are encountered.

An exact case-sensitive match for the English phrase that needs to be translated. If there is a (fr_CA + Fr) translation value present, it is used in absolute precedence.
If the English phrase is in titlecase, e.g. "Launch presentation", we repeat the check, looking for all lower-case e.g. "launch presentation".
If the English phrase is in lowercase, e.g. "launch presentation", we repeat the check, looking for all lower-case e.g. "Launch presentation".
If the phrase has a trailing "{~clarification}", this is removed and above repeated. We currently don't do this for embedded clarifications, only trailing.
If we still cannot find a match, the English phrase is used.

Getting help

If you need help with any of this process, or the data file structure, or with a particular phrase's contextual meaning, don't hesitate to get in touch at the Omniscope Translation forums.