Translations Manual
Beginning with the 5.0 release, multi-language support became available in the SOS software. As SOS installations have become widespread internationally, the impact of its educational outreach has become hindered by its lack of support for non-English speaking administrators, presenters, and the viewing public. Additionally, many countries, including the United States, have large populations that have English as their second language. So to increase the reach of science education, SOS now has the ability to use non-English languages in its software.
A number of components in the SOS Product Suite, specifically the SOS Remote App (“Remote App”), SOS Public Kiosk (“Public Kiosk”), and Visual Playlist Editor (“VPLE”) all support localized user interfaces (UIs), which include dynamic translation of text in labels, buttons, and dialog boxes to a native language. The SOS Data Catalog also supports localization of dataset names and descriptions, major and sub categories, and keywords, including language variations in different countries. Data Catalog localization is supported in the Remote App, the Public Kiosk and the VPLE.
In most cases, NOAA will not be creating translations for SOS, but will rely on others such as SOS distributors, content creators, and sites where English is not the primary language to create translations in their preferred languages. NOAA will readily share high quality contributed SOS translations in different languages for the benefit of the entire SOS community.
Currently, the SOS Product Suite is most focused on simple language translations, but plan to implement additional forms of localization over time, based upon user requests.
Definitions
Permalink to Definitions- Translation
- The process of changing an source language text (in this case American English) to another language by substituting words from one language to another in context
- Localization
- A more specialized process of adapting text and other content for different countries or regions. It goes beyond translation to modify the source language and other elements to meet cultural preferences in the other language
- Locale
- The combination of a language with a country or region. SOS follows
industry standards for locale, including an ISO 639 language
code, generally two lower case letters, and an ISO 3166
country code, generally two upper case letters, with an
underscore character separating them. For example, the locale for
American English is
en_US
. Throughout this document, we refer to a locale generically as “xx_YY”, where xx = a language code and YY = a country code. While there are more complex locale standards available, these simpler ISO standards should cover all SOS locations worldwide
Principal Types of Localizations
Permalink to Principal Types of LocalizationsTranslation support in SOS is divided into two principal types: dataset translations and user interface translations.
Dataset Translations
Permalink to Dataset TranslationsTranslations of dataset text is stored in the Data Catalog and is available to all localized SOS applications.
- Dataset names and descriptions are translated by using either SOS playlists edited in a text editor or tab separated value (tsv) files edited in a spreadsheet application (like Excel or Google Sheets)
- Highlights (spotlight) dataset temporary names and “why” descriptions are translated by using highlights dataset (hds) files edited in a text editor
- Major category, subcategory, highlights category, and keywords are translated using comma separated value (csv) files in a spreadsheet application (like Excel or Google Sheets).
User Interface Translations
Permalink to User Interface TranslationsTranslations of UI text are stored in specific files under /shared/sos/locale on the SOS machine and are not shared between SOS applications.
- Remote App translations are defined using tab separated value (tsv) files in a spreadsheet application and converted to an Apple strings file format
- Public Kiosk translations are made using the Kiosk Administration User Interface and the 3rd-party Qt Linguist program on the Kiosk machine
- Visual Playlist Editor UI translations are made using tab separated value (tsv) files in a spreadsheet application (like Excel or Google Sheets) and the 3rd-party Qt Linguist program on the SOS machine
Each of the these types of translations will be discussed separately in the sections below, with the exception of localization for the Public Kiosk, which is covered in the Public Kiosk Manual. For general assistance on performing translations for SOS, please contact sos.support@noaa.gov.
Dataset Translations
Permalink to Dataset TranslationsTranslation files for datasets and related metadata in the SOS Data Catalog reside on the SOS machine under the /shared/sos/locale directory. There are three types of files used to translated datasets. Dataset name and description translations are defined in SOS playlists and in tab separated value (tsv) files, while major categories, subcategories, and keywords are defined in comma separated value (csv) files.
Each translation file follows the naming convention “xx_YY.zzz”, where “xx” is the [ISO 639 language code][iso-369], “YY” is the ISO 3166 country code, and “zzz” is the file format extension (sos, tsv, or csv). The locale information is extracted from the playlist filename, so it is critically important to use the correct language and country codes for the language being translated. All the translations for each language/country combination are defined together in the same sos, tsv, and csv files.
It is not required to supply translations for the entire SOS Data Catalog at once for a locale. Any dataset information without translations will remain in English and you can add more translations incrementally at any time.
English Language Overrides
Permalink to English Language OverridesThe default locale is “en_US”, which is English in the United States. However, you are allowed to use en_US.sos, .tsv, and .csv files to make “translations.” While these aren’t technically translations, the definitions specified will override the default English information in the SOS Data Catalog, giving you the opportunity to customize the text there, if desired.
Dataset Translation Playlists
Permalink to Dataset Translation PlaylistsThere are two options for translating the names and descriptions of datasets and their variations. The first of these is using standard SOS playlists (see the TSV Files section to use the other option). Either option works well, but playlists must be used if you have longer descriptions that require multiple paragraphs.
For translations, each dataset or variation is specified by three playlist
properties: an include
property with the dataset playlist path, a rename
property with a translated name, and a description
property with a translated
description on one or more lines enclosed between {{ }}
characters.
Translating Dataset Playlists for a New Language
Permalink to Translating Dataset Playlists for a New Language- Generate playlist files from the SOS dataset catalog using
translations2db --generate_playlist
(see the translations2db Command Line Utility section for details) - Copy /shared/sos/locale/generated/en_US.sos from to
/shared/sos/locale/xx_YY.sos, following the
xx_YY.sos
locale naming convention for the language and country for which you want to create a translation - Replace the English values (to the right of the equals sign) for the
rename and description keywords with translated values in a Linux text
editor, such as
vi
orgedit
. Be sure the description text is enclosed between{{
and}}
characters - Reload your dataset translations into the SOS Data Catalog using either
the SOS Stream GUI or
translations2db --load_playlists
(see the translations2db Command Line Utility section for details)
Editing Dataset Playlist Translations for an Existing Language
Permalink to Editing Dataset Playlist Translations for an Existing LanguageEditing a translation (or English override text) is done by simply modifying
the values to the right of the equals sign of either rename or description
keywords for any datasets in a translation playlist with your favorite text
editor. Be sure the description text is enclosed between {{
and
}}
characters. Should you wish to remove a particular translation entirely,
just delete the lines containing include, rename, and description for any
datasets you no longer want.
TSV Files
Permalink to TSV FilesThe second option for translating the names and descriptions of datasets and their variations is with tab separated value (tsv) files. Either option works well, but tsv files have the advantage of being easily loaded into a standard spreadsheet for convenient editing. For translations, each dataset or variation is specified by four columns: A is the dataset ID number in the Data Catalog, B is the playlist file path, C is the dataset name, and D is the dataset description.
One highly efficient way to use this option is to upload the dataset tsv file you want to translate into a Google Sheet using Google Drive and then use the Google Translate formula to automatically translate all the text.
To complete the translation for this example, copy column C over column B (using Paste special > Paste values only), delete column C, then repeat these same steps for the the dataset descriptions. Once the translations are all pasted as values they may be edited by hand to fix errors and improve the quality of the translations.
The final steps are to download this as a tsv file, copying it into /shared/sos/locale/zh_TW.tsv (replacing the original file there).
Reload your dataset translations into the SOS Data Catalog using
translations2db --load_dataset_tsv
(see the translations2db Command Line
Utility section for more details).
Highlights (Spotlight) Translations
Permalink to Highlights (Spotlight) TranslationsHighlight (spotlight) datasets were added in SOS 5.3 and are a small set of SOS datasets periodically selected by the NOAA SOS Team in Boulder. They provide an easy way to gradually explore the SOS Data Catalog over time and enable quick access to datasets that highlight timely events. Translations for these datasets are specified by a combination of normal dataset translations made in .sos or .tsv files and additional definitions in highlights dataset (.hds) files, which have a similar structure to a playlist. Note that highlights datasets are also associated with Highlights Categories used to classify a particular kind of highlights dataset. These are translated separately in the same csv files used for other dataset categories and keyword (see the following section).
For translations, each highlights dataset or variation is specified by several
properties: an include property with the dataset playlist path, a
TemporaryDatasetName property with a translated name (only used for temporary
datasets), and a WhyDescription property with a translated description of why
the dataset is being highlighted on one or more lines enclosed between {{ }}
characters. Note that the dataset name is not translated in the
hds file unless it is temporary (i.e., not in the SOS data catalog).
Regular dataset name translations are already made using .sos or
.tsv files (see the previous section).
Translating Highlights (Spotlight) Datasets for a New Language
Permalink to Translating Highlights (Spotlight) Datasets for a New Language- Generate hds files from the SOS dataset catalog using
translations2db --generate_highlights
(see the translations2db Command Line Utility section for details) - Copy /shared/sos/locale/generated/en_US.hds from to
/shared/sos/locale/xx_YY.hds, following the
xx_YY.sos
locale naming convention for the language and country for which you want to create a translation. - Replace the English values (to the right of the equals sign) for the
TemporaryDatasetName and WhyDescription keywords with translated values in
a Linux text editor, such as
vi
orgedit
. Be sure theWhyDescription
text is enclosed between{{
and}}
characters - Reload your dataset translations into the SOS Data Catalog using either
the SOS Stream GUI or
translations2db --load_highlights
(see the translations2db Command Line Utility section for details)
Editing Highlights (Spotlight) Dataset Translations for an Existing Language
Permalink to Editing Highlights (Spotlight) Dataset Translations for an Existing LanguageEditing a translation (or English override text) is done by simply modifying
the values to the right of the equals sign of either TemporaryDatasetName
or
WhyDescription
keywords for any datasets in an hds file with your favorite
text editor. Be sure the WhyDescription
text is enclosed between
{{
and }}
characters. Should you wish to remove a particular
translation entirely, just delete the lines containing include
,
TemporaryDatasetName
, and WhyDescription
for any highlights datasets you no
longer want.
Dataset Category and Keyword Translations
Permalink to Dataset Category and Keyword TranslationsThe SOS Data Catalog uses categories and keywords to organize and provide
searching capabilities for the hundreds of datasets it holds. Each dataset has
at least one “Major Category” and “Subcategory” to classify it and usually has
one or more “Keywords” pertaining to its content. Each highlights (spotlight)
dataset also has a “Highlights Category”. These metadata entities are localized
using comma separated value (csv) files. Csv is a common import/export format
for spreadsheets, such as Excel or Google Sheets. The csv files follow the
naming convention xx_YY.csv
, where “xx” is the [ISO 639][iso-369] language
code and YY is the ISO 3166 country code. The default locale is
en_US, which is English in the United States. However, if an en_US.csv file is
present, it will not be imported into the SOS Data Catalog since American
English values are already defined by default.
Each row in the csv file includes the type of metadata, the English text, and the translated text.
Translating Categories and Keywords for a New Language
Permalink to Translating Categories and Keywords for a New Language- Create an en_US.csv file (see the translations2db Command Line Utility section for details)
- Rename it to the correct locale name following the
xx_YY.csv
naming convention - Load it into a spreadsheet program (or a text editor if preferred)
- Replace the last column of English text with translated values. Do not modify the text in the first two columns
- Export back to csv (if using a spreadsheet). Be sure the
xx_YY.csv
file is placed in the /shared/sos/locale/ directory - Load the
xx_YY.csv
file into the SOS Data Catalog using either the SOS Stream GUI or translations2db command line utility
Editing Category and Keyword Translations for an Existing Language
Permalink to Editing Category and Keyword Translations for an Existing Language- Load an existing
xx_YY.csv
file into a spreadsheet program (or a text editor if preferred) - Update the last column of translated text with your edits. Do not modify the text in the first two columns
- Export back to csv (if using a spreadsheet). Be sure the
xx_YY.csv
file is placed in the /shared/sos/locale/ directory - Reload the
xx_YY.csv
file into the SOS Data Catalog using either the SOS Stream GUI or translations2db command line utility
Remote App Translations
Permalink to Remote App TranslationsThe Remote App for the iPad is the main controller for SOS for presenters. It has a rich user interface (UI) that includes many labels, buttons, and dialog boxes. The iPad has the ability to set the Language and Country from the Settings app, which automatically translates those Apps that have that capability.
Apple provides built-in translation capabilities that require a particular format, which is a type of property-value pair file called a strings file. In the case of the Remote App, the user interface elements that have only one or a few English language words are matched and translated on-the-fly using the strings file. Other user interface elements, such as more verbose messages, use placeholder text of a few words (preceded by “^”) that is used to look up translations.
The Apple strings file format is not particularly convenient for editing by a
human translator, so for translating the Remote App, SOS uses tab separated
value (tsv) files that are placed under /shared/sos/locale/iOS.
Like csv, tsv is a common import/export format for spreadsheets, such as Excel
or Google Sheets. Tsv is used instead of csv here because commas frequently
occur in the Remote App UI text, while tabs do not. The tsv files follow the
naming convention xx.tsv
, where xx is the [ISO 639][iso-369] language code
(country codes are not currently used for the Remote App UI translations). The
default locale is “en”, which is English. Like the translations described above
that are loaded into the Data Catalog, the en.tsv file can be used
to override the default English text in the iPad Remote App UI. This is unlikely
to be used routinely, but is available to anyone wishing to do some minor
customization of the Remote App UI text or to fix typos between releases.
Each row in the tsv file includes either the actual English text or special key text prefixed by “^”, and the translated text.
Text enclosed between /* */ characters are informational comments used to identify what part of the UI is being translated and are not part of the translation. Note that any missing translations will be shown in the Remote App in English by default.
Translating the Remote App UI for a New Language
Permalink to Translating the Remote App UI for a New Language- Copy the
en.tsv
file in /shared/sos/locale/iOS to the correct locale name following thexx.tsv
naming convention (contact SOS Support to obtain this file if it is not already on your system) - Load it into a spreadsheet program such as Google Sheets (or a text editor if preferred)
- Replace the last column of English text with translated values. Do not modify the text in the first column. You can use Google Translate in a cell formula to automate this process (see the VPLE UI Translation section for a similar example of how to do this)
- Export back to tsv (if using a spreadsheet). Be sure the
xx.tsv
file is placed in the /shared/sos/locale/iOS/ directory - Convert the
xx.tsv
file to.xx.strings
using either the SOS Stream GUI or translations2db command line utility
Editing the Remote App UI Translations for an Existing Language
Permalink to Editing the Remote App UI Translations for an Existing Language- Load the
xx.tsv
file in /shared/sos/locale/iOS into a spreadsheet program such as Google Sheets (or a text editor if preferred) - Update the last column of translated text with your edits. Do not modify the text in the first column
- Export back to tsv (if using a spreadsheet). Be sure the
xx.tsv
file is placed in the /shared/sos/locale/iOS/ directory - Convert the
xx.tsv
file to.xx.strings
using either the SOS Stream GUI or translations2db command line utility
Displaying the Remote App UI Translations
Permalink to Displaying the Remote App UI TranslationsIn order for the Remote App to use translations, the iPad device Settings app (the gear symbol) must first be used to the change the locale. Here is an example on how to set the Language & Region settings to German in Germany:
First, set the Region to Germany (DE).
Second, set the Language to German (de).
Changing the device’s Language & Region will also cause all the basic iOS controls to use that locale’s language as well. After the device locale is set, then the Remote App will automatically transfer the corresponding translations file from /shared/sos/locale/iOS. For this example, the file would be .de.strings.
Public Kiosk Translations
Permalink to Public Kiosk TranslationsIn the Public Kiosk, translations are created and edited in several different ways depending on which part of the kiosk is being localized.
Translations made on the Kiosk machine
Permalink to Translations made on the Kiosk machinePublic UI text translations are created and edited using the Language tab in the Admin UI on the Windows kiosk machine.
Administration UI text translations are made using a set of utilities run on the Windows kiosk machine. This is a more advanced localization activity that may require assistance from the SOS team. Steps to perform a translation of the Admin UI are described in the Admin UI Translations section.
Translations made on the SOS machine
Permalink to Translations made on the SOS machineKiosk dataset names and descriptions are translated using the SOS Data Catalog and playlists as described in the Kiosk Dataset Translations section.
Group names are translated using playlists as described in the Group Name Translations section.
After finishing your dataset and group translation changes, run media2kiosk, then transfer the resulting files to the kiosk machine using the FTP tab in the Admin UI.
Kiosk Dataset Translations
Permalink to Kiosk Dataset TranslationsThe names and descriptions for datasets in the Public Kiosk are generated by the media2kiosk utility and are written to directories under /shared/sos/kiosk/datasets, where they are used by the kiosk after being transferred there.
Here is a summary of where the dataset informational text displayed in the kiosk comes from:
- The default locale (en_US) names and descriptions are read from the SOS Data Catalog. The descriptions are stripped of any HTML formatting that may have been used
- If there are any translations previously imported into the SOS Data Catalog, those are automatically extracted as well for each of their locales. More information on dataset name and description translations in the Data Catalog is in the Dataset Translations section
- Playlists may also be used to define translations for dataset names and descriptions. These are very similar to the localization playlists used more generally in SOS, which are described in the Dataset Translation Playlists section. How to use these translation playlists is explained next
Translation playlists for datasets reside on the SOS machine under the
/shared/sos/kiosk/playlists/locale/datasets directory. This
directory holds a set of playlists following the naming convention xx_YY.sos
,
where “xx_YY” is the locale code, as described earlier. All the dataset
translations for a given locale are placed together in the same playlist. You
may notice that there is an en_US.sos playlist under the datasets
sub directory. This does not contain translations per se, but the file
contains entries for all the datasets in the default kiosk configuration with
shortened dataset names and descriptions. This was done to work better for
viewing by the general public and can be thought of as a way to override the
Data Catalog text.
English Sample
Permalink to English SampleFor reference, here is a portion of the en_US.sos playlist for datasets, which includes two datasets:
Each of the two datasets shown uses three playlist keywords that are applicable to translations:
include =
path to the dataset playlistrename =
kiosk name for the datasetdescription =
kiosk description for the dataset. Description is a dataset playlist property first introduced in SOS 5.0. The description may have multiple lines, but must always be enclosed between{{
and}}
characters
Translations to other languages work exactly the same way, except that the values for rename and description will not be in English.
Traditional Chinese Sample
Permalink to Traditional Chinese SampleFor example, here are the same two datasets in Traditional Chinese from the translation playlist /shared/sos/kiosk/playlists/locale/datasets/zh_TW.sos:
How to Edit Translations
Permalink to How to Edit TranslationsEditing a translation (or English override text) is done by simply modifying
the values to the right of the equals sign of either rename
or description
keywords for any datasets in a translation playlist with your favorite text
editor. Be sure the description
text is enclosed between {{
and
}}
characters. Should you wish to remove a particular translation entirely,
just delete the lines containing include
, rename
, and description
for any
datasets you no longer want.
How to create translations for a new language:
Permalink to How to create translations for a new language:The easiest way to add another language for dataset translations is to start by
making a copy of the en_US.sos file, then renaming the copied file
to use the locale code to your new language. For example, if you wanted to add
Turkish, you would use a file named tr_TR.sos copied from
en_US.sos. In the new file, replace the English text values with
your new language translations to the right of equals sign for the rename
or
description
keywords. Be sure the description
text is enclosed between {{
and }}
characters.
How to add additional datasets to translations:
Permalink to How to add additional datasets to translations:If you have modified your kiosk configuration by including datasets not found
in the NOAA-defined default configuration, the include
paths for those
datasets will be set in your group playlists (see the section Group and
Dataset Configuration in the Public Kiosk Manual).
To add these to your translation playlists, just copy the include
lines and
add rename
and description
keywords for each one. Be sure the description
text is enclosed between {{
and }}
characters.
Deploying Your Translations
Permalink to Deploying Your TranslationsAfter finishing your translation changes, run media2kiosk, as
the sos
user, then transfer the resulting files to the kiosk machine using
the FTP tab in the Admin UI.
Group Name Translations
Permalink to Group Name TranslationsThe names for groups in the Public Kiosk are generated by the media2kiosk utility and are written to directories under /shared/sos/kiosk/groups, where they are used by the kiosk after being transferred there.
Here is a summary of where the group text display in the kiosk comes from:
- The default locale (en_US) names are the filename stems extracted from group playlist filenames. For example, the playlist /shared/sos/kiosk/playlists/groups/air.sos would have the group name “air”
- Playlists may also be used to define translations for group names. How to use these translation playlists is explained next
Translation playlists for groups reside on the SOS machine under the
/shared/sos/kiosk/playlists/locale/groups directory. This directory holds a
set of SOS playlists following the naming convention xx_YY.sos
, where “xx_YY”
is the locale code, as described earlier. All the group translations for a
given locale are placed together in the same playlist. You may notice that
there is an en_US.sos
playlist under the groups
sub directory. This does
not contain translations per se, but the file contains entries for all
the groups in the default kiosk configuration with slightly different text. For
example, the name for the group defined in air.sos
is “Air”. This was done to
make more attractive looking group labels for the general public and can be
thought of a way to override the filename stem text.
Groups are translated similarly to datasets, except that there is no description. Here is an example of a Traditional Chinese translation for the kiosk groups in /shared/sos/kiosk/playlists/locale/groups/zh_TW.sos:
After finishing your translation changes, run media2kiosk, then transfer the resulting files to the kiosk machine using the FTP tab in the Admin UI.
Admin UI Translations
Permalink to Admin UI TranslationsThe Administration User Interface (Admin UI) in the Public Kiosk may be localized to other languages. Translating the Admin UI is distinctly different than translating the Public UI, group names, and dataset names and descriptions. This activity is non-trivial, so please feel free to contact SOS Support for assistance if you need help beyond what is laid out here.
The Admin UI uses a third-party application called Qt Linguist to
assist you in translating from English to another language. You can also use
Linguist to modify any existing translations. As shown in Appendix A in the
Public Kiosk Manual, there are two translation
files for each locale under C:\shared\sos\kiosk\config\admin:
xx_YY.ts
and xx_YY.qm
, where “xx” = language, “YY” = country or region,
.ts = raw (ASCII) translation format, and .qm =
compiled (binary) translation format. You do not need to know details about
these formats to perform your translations.
Translating the Kiosk Admin UI for a New Language
Permalink to Translating the Kiosk Admin UI for a New Language- If it is running, close the kiosk application on the Windows machine
- Open Windows Explorer from the Start Menu, navigate to C:\shared\bin, and double click on linguist.exe. The Qt Linguist user interface will be displayed
-
From the menu bar, select FileOpen.... In the file browser that pops up, navigate to C:\shared\sos\kiosk\config\admin. Double click on en_US.ts to open the English language raw translations file and display the contents
- From the menu bar, select FileSave As.... In the file browser that pops up, enter the raw translation filename for locale you want. For example, for French in France, type fr_FR.ts. Click the Save button to create the new file
-
From the menu bar, select EditTranslation File Settings.... In the popup window, change the “Target Language” settings to match the language and country for your translation. For fr_FR, the settings will be “Language: French, Country/Region: France”
- Using the Linguist controls, go through each English text element by selecting first the “Context” item and then the first “Source text” item. Replace the English text in the French translation box with your translation. Then click the green Checkmark icon next to the item or in the toolbar to accept the translation. Note that you may also fill in the “French translator comments” box if you wish, but that text will not appear in the kiosk
-
After translating all the “Source text” elements for the first “Context” item, select the next “Context” item and translate all its “Source text” elements. Continue in this fashion through the last “Context” item
- From the menu bar, select FileSave to save your translations to the raw translations file
- From the menu bar, select FileRelease to write your translations to the compiled (binary) translations file
-
Test your translations in the kiosk. You will need to be sure your new locale
is included in the
locale_options
property list (see Properties Tab section of the Public Kiosk Manual) so you can select its button on the right side of the “Title Area”
Visual Playlist Editor Translations
Permalink to Visual Playlist Editor TranslationsThe Visual Playlist Editor (VPLE) was released with full functionality beginning in SOS 5.1, replacing the previous playlist editor. The VPLE visually lays out, modifies, and previews SOS playlist content in a flat map display.
The VPLE UI uses a third-party application called Qt Linguist to
assist you in translating from English other languages. You can use Linguist for
new translations or to edit any existing translations. There are two translation
files for each locale under the linked directory
/shared/sos/locale/playlist_editor: xx_YY.ts
and xx_YY.qm,
where xx = language (the ISO 639 language code), YY = country or
region (the ISO 3166 country code), .ts = raw (ASCII)
translation format, and .qm = compiled (binary) translation format.
You do not need to know details about these formats to perform your
translations.
The basic workflow to follow when translating the VPLE UI to a new language begins by performing a bulk translation of the text using automated translation software such as Google Translate. This activity consists of a number of steps to prepare the text for loading into a spreadsheet, creating the translations, and converting back to a raw translations file. You can then use Linguist to fix errors and bad translations that were automatically generated.
Here are the steps to create translations of VPLE UI text to a new language. If you are editing an existing translation, just skip to step 6. We will use French as an example.
-
Open a command shell and type the following commands (without the $ and substituting the locale you will be using, i.e., fr_FR.ts for French - fr in France - FR):
$ cd /shared/sos/locale/playlist_editor $ cp en_US.ts fr_FR.ts $ translations2db --vple_ts_to_tsv
A set of tab separated value (tsv) files in the form
xx_YY.tsv
will be created, one for each ts file. In the tsv files, VPLE user interface text strings are specified by three columns separated by tabs: Column A is the Context name (internal to the VPLE), B is text in English, and C is (currently) the same text as in column B, which we will be replacing with our translations - If you have a Google Drive account, you can use Google Translate in a web browser to bulk translate the text in your tsv file to many different languages. After logging in to your Google Account, upload the dataset tsv file you want to translate into a Google Sheet. If you don’t wish to do a bulk translation, you can skip ahead to Step 6, using the Linguist application
-
Use Google Translate cell formulas to automatically translate all the text in one column to a new column. Below is an example of part of a fr_FR.tsv file imported to a Google Sheet, with translations of English text in column B to French in column C. The formula entered for the highlighted cell (C1) is shown in the function (fx) field. This formula should be copied to all the cells in column C to perform the full set of translations
-
With the Google Translation done, download the sheet as a tsv file and copy it
into
/shared/sos/locale/playlist_editor/fr_FR.tsv
(replacing the original file there) -
In a command shell, type the following command:
translations2db --tsv_to_vple_ts
. This writes the translations from Google Translate back into the ts translation format. A set of files in the formxx_YY.tsv
will be created, including thefr_FR.ts
example here -
In a command shell, type the following commands:
$ cd /shared/sos/locale/playlist_editor $ /shared/sos/visual_playlist_editor/default/launch_linguist
The Qt Linguist main window opens up
-
From the menu bar, select FileOpen and select fr_FR.ts to edit your French translations. A Settings dialog box may pop up automatically, but if it doesn’t, from the menu bar, select EditTranslation File Settings…. In the “Settings” dialog box, fill in the “Target language” information for your new locale and press OK
-
Using the Linguist controls, go through each English text element by selecting first the Context item and then the first Source text item. If you wish to make a change, replace the English text in the French translation box with your revised translation. Then click the green Checkmark icon next to the item or in the toolbar to accept the translation edit. Do not type anything in the French translator comments box. The example below shows the translation for Name in the AboutTab Context.
After examining and making selected changes to all the “Source text” elements for the first “Context” item, select the next “Context” item and go through all its “Source text” elements. Continue in this fashion until reaching the end of the last “Context” item
-
You may see that some of the check marks are yellow. This happens when the formatting of the translated text is incorrect. You must fix all of these before your translations are complete! There are two common types of formatting issues to correct:
- accelerators are “&” symbols
- place markers are in the form “%n” with n either 0 or 1 (this is where text determined while the VPLE is running, like a file name, is inserted into the translated text)
To fix these issues, edit the translation so the “&”, “%0”, and “%1” look the same in the translated language as with English (with no extra spaces and in the correct order). Linguist will indicate whether there is still or problem or not. Click the green check mark after each formatting error is fixed
- From the menu bar, select FileSave to save your translations to the raw translations ts file (fr_FR.ts in this example)
- From the menu bar, select FileRelease to write your translations to the compiled (binary) translations file. In this example, the file will be named fr_FR.qm
- You are now ready to test your translations. When you run the VPLE, from the menu bar, select the Languagefrançais and the user interface text should switch to French. If you find any missing or incorrect translations, return to Linguist to examine and edit the French text, making sure to “Save“ and “Release” to prepare your changes for the VPLE
Using Stream GUI
Permalink to Using Stream GUIThe SOS Stream GUI itself cannot be translated itself, but it does provide a number of interactive controls to run translation actions under the Library and the Utilities menus. These menu items actually run a command line utility behind the scenes called translations2db with different options. The menu items provide convenient access to the most commonly used translation operations.
Library Menu
Permalink to Library Menu“Perform Translations…” reruns all the translation operations for datasets, related metadata, and Remote App UI. This should be used any time immediately after the “Update Library…” item has been called, because that operation clears all the translations from the Data Catalog.
Utilities Menu
Permalink to Utilities MenuThere are four translation items in the Utilities menu.
Load Dataset Translations…
Permalink to Load Dataset Translations…Reads all the playlists (files with the pattern xx_YY.sos
) in
/shared/sos/locale/ and loads the translated dataset names and descriptions
into the SOS Data Catalog. This command is useful when adding the dataset
translations to see how they appear in the iPad (after updating the Data
Catalog there). It is equivalent to running translations2db --load_playlists --verbose
on the command line.
Load Category/Keyword Translations…
Permalink to Load Category/Keyword Translations…Reads all the csv files (with the pattern xx_YY.csv
) in /shared/sos/locale/
and loads the major category, subcategory, and keyword translations into the
SOS Data Catalog. This command is useful when adding the category/keywords
translations to see how they appear in the iPad (after updating the Data
Catalog there). It is equivalent to running translations2db --load_csv --verbose
on the command line.
Clear All Data Catalog Translations…
Permalink to Clear All Data Catalog Translations…Removes all the translations in the Data Catalog for dataset name and
description and for major categories, subcategories, and keywords. This command
is useful to delete any prior translations made and start over without
localization. It is equivalent to running translations2db --remove_all
on the
command line.
Prepare iOS Translations…
Permalink to Prepare iOS Translations…Reads all the tsv files (with the pattern xx.tsv
) in /shared/sos/locale/iOS
and converts them into xx.strings
files. This command is useful when adding
user interface translations to see how they appear in the Remote App. It is
equivalent to running translations2db --tsv_to_ios_strings --verbose
on the
command line.
translations2db Utility
Permalink to translations2db UtilityAll translation operations are performed by using the translations2db
utility, either indirectly from a menu item in the SOS Stream GUI
or directly on the command line. This tool is installed in
/shared/sos/default/bin. There are a number of options, all of which begin
with --
. Different options may sometimes be run together at the same time,
e.g., translations2db --load_playlists --load_csv --verbose
.
Options
Permalink to Options--help
Permalink to --helpLists all the valid options and their purpose.
--load_playlists
Permalink to --load_playlistsUse to load dataset translations.
Loads dataset name and description translations defined in playlist files
normally located in /shared/sos/locale to the data catalog. This option is an
alternative to --load_dataset_tsv
for loading dataset translations. It
accepts multi-line descriptions and uses the standard SOS playlist format.
If both --load_playlists
and --load_dataset_tsv
options are used together,
playlists will take precedence over tsv files for the same locales.
--load_dataset_tsv
Permalink to --load_dataset_tsvUse to load dataset translations.
Loads dataset name and description translations defined in tab separated value
(tsv) files normally located in /shared/sos/locale to the data catalog. This
option is an alternative to --load_dataset_tsv
for loading dataset
translations. It does not allow multi-line descriptions, but tsv files are
easily loaded into spreadsheet programs, such as Excel or Google Sheets, for
convenient editing.
If both --load_playlists
and --load_dataset_tsv
options are used together,
playlists will take precedence over tsv files for the same locales.
--load_csv
Permalink to --load_csvUse to load category and keyword translations.
Loads translations for major categories, subcategories, highlights categories, and keywords from comma separated value (csv) files normally located in /shared/sos/locale to the data catalog. Csv files are easily loaded into spreadsheet programs, such as Excel or Google Sheets, for convenient editing.
--load_highlights
Permalink to --load_highlightsUse to load highlights (spotlight) dataset translations.
Loads translations for highlights (spotlight) datasets from highlight dataset (hds) files normally located in /shared/sos/locale to the data catalog. Hds files are formatted similarly to playlists, but are specific to spotlight datasets, which can be temporary datasets not found elsewhere in the data catalog.
--load_all
Permalink to --load_allUse to load all dataset-related translations.
Loads translations from playlist, csv, and hds files normally located in
/shared/sos/locale to the data catalog. This is equivalent to specifying all
of --load_playlists
, --load_csv
, and --load_highlights
.
--remove_all
Permalink to --remove_allUse to clear all data-related translations loaded previously.
Removes all translations of dataset names & descriptions, highlights datasets, major & sub categories, highlights categories, and keywords, leaving only the default English text.
Does not affect user interface translations for the Remote App, Visual Playlist Editor, or any Kiosk-specific translations.
--tsv_to_ios_strings
Permalink to --tsv_to_ios_stringsUse to create translation files used by the Remote App user interface.
Converts translations for the Remote App’s user interface defined in tab separated value (tsv) files normally located in /shared/sos/locale/iOS to a special Apple strings format.
All iPad translations should be made to the tsv files, not in the generated strings files.
--vple_ts_to_tsv
Permalink to --vple_ts_to_tsvUse to prepare translation files used by the Visual Playlist Editor user interface for editing in a spreadsheet.
Converts Visual Playlist Editor translation files in the ts format to tab separated value (tsv) files located in the linked directory /shared/sos/locale/playlist_editor. Tsv files are easily loaded into spreadsheet programs, such as Excel or Google Sheets, for convenient editing.
Do not use both --vple_ts_to_tsv
and --tsv_to_vple_ts
options together.
--tsv_to_vple_ts
Permalink to --tsv_to_vple_tsUse to prepare translations edited in a spreadsheet for use by the Playlist Editor user interface.
Converts tab separated value (tsv) formatted files from a spreadsheet to the ts format used by the Playlist Editor user interface. Files must be located in the linked directory /shared/sos/locale/playlist_editor.
Do not use both --vple_ts_to_tsv
and --tsv_to_vple_ts
options together.
--generate_playlists
Permalink to --generate_playlistsUse to extract dataset translations from the data catalog into SOS playlists.
Generates playlists containing dataset names and descriptions for all the
locales in the data catalog. These files are written to a generated
subdirectory (normally /shared/sos/locale/generated). Any playlists
previously generated will be overwritten. Only one of --generate_playlist
and
--generate_dataset_tsv
options is typically used at a time.
The generated files may be copied to the root locale directory (normally
/shared/sos/locale) to update the dataset translations. They can also be used
as a starting point for translating a new language. The updated translations
are then loaded back into the data catalog with the --load_playlists
option.
--generate_dataset_tsv
Permalink to --generate_dataset_tsvUse to extract dataset translations from the data catalog for editing in a spreadsheet.
Generates tab separated value (tsv) files containing dataset names and
descriptions for all the locales in the data catalog. These files are written
to a generated subdirectory (normally /shared/sos/locale/generated). Any tsv
files previously generated will be overwritten. Only one of
--generate_playlist
and --generate_dataset_tsv
options is typically used at
a time.
The generated files may be copied to the root locale directory (normally
/shared/sos/locale) and edited in a spreadsheet, such as Excel or Google
Sheets, to update the dataset translations. They can also be used as a starting
point for translating a new language. The updated translations are then saved
back to tsv files and loaded back into the data catalog with the
--load_dataset_tsv
option.
--generate_csv
Permalink to --generate_csvUse to extract category & keyword translations from the data catalog for editing in a spreadsheet.
Generates comma separated value (csv) files containing major categories, subcategories, and keywords for all the locales in the data catalog. These files are written to a generated subdirectory (normally /shared/sos/locale/generated).
The generated files may be copied to the root locale directory (normally
/shared/sos/locale) and edited in a spreadsheet, such as Excel or Google
Sheets, to update the category and keyword translations. They can also be used
as a starting point for translating a new language. The updated translations
are then saved back to tsv files and loaded back into the data catalog with the
--load_csv option
.
--generate_highlights
Permalink to --generate_highlightsUse to extract highlights dataset translations from the data catalog into hds files.
Generates hds files containing highlights (spotlight) dataset names and descriptions for all the locales in the data catalog. These files are written to a generated subdirectory (normally /shared/sos/locale/generated). Any playlists previously generated will be overwritten.
The generated files may be copied to the root locale directory (normally
/shared/sos/locale) to update the highlights dataset translations. They can
also be used as a starting point for translating a new language. The updated
translations are then loaded back into the data catalog with the
--load_highlights
option.
--verbose
Permalink to --verboseUsed for troubleshooting.
Write timestamps with logged messages (must appear before --logging
).
--logging
Permalink to --logging--logging [level]
Used for troubleshooting.
Set logging level for messages (default is INFO
). Valid level values are:
FATAL
, ERROR
, WARN
, INFO
, DEBUG
, TRACE
.
--root
Permalink to --root--root [directory]
Used for troubleshooting.
Use a different translations root directory (default is /shared/sos/locale). The root directory is where all translation files (both original and generated) reside, except for Public Kiosk files which are in directories under /shared/sos/kiosk (see Public Kiosk Manual for more information).
--use_alternative_db
Permalink to --use_alternative_dbUsed for troubleshooting.
Use an alternate database in the --root
directory copied from
/shared/sos/database. Do not use for the iPad!
--generate_sosx_tsv
Permalink to --generate_sosx_tsvFor NOAA Internal Use.
Generates tab separated value (tsv) files containing dataset names and descriptions for all the locales to work with SOS Explorer®. These files are written to a generated subdirectory (normally /shared/sos/locale/generated). An SOSX tsv file previously generated will be overwritten.