Translations Manual

Overview

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.

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.

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.

Principal Types of Localizations in SOS

Translation support in SOS is divided into two principal types.

SOS Data Catalog Datasets and Associated Metadata

Translations of dataset text is stored in the Data Catalog and is available to all localized SOS applications.

  1. Dataset names and descriptions are translated by using either SOS playlists edited in a text editor or tab separated value (tsv) files edited n a spreadsheet application (like Excel or Google Sheets).
  2. Major category, subcategory, and keywords are translated using comma separated value (csv) files in a spreadsheet application (like Excel or Google Sheets).

User Interfaces of SOS Product Suite Applications

Translations of UI text are stored in specific files under /shared/sos/locale on the SOS machine and are not shared between SOS applications.

  1. Remote App translations are defined using tab separated value (tsv) files in a spreadsheet application and converted to an Apple strings file format.
  2. Public Kiosk translations are made using the Kiosk Administration User Interface and the 3rd-party Qt Linguist program on the Kiosk machine.
  3. 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 at sos.gsd@noaa.gov.


Dataset Translations

Translation 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, 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

The 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

There 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 Dataset Translation 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.

Here is an example of part of a zh_TW.sos playlist used to translate Traditional Chinese in Taiwan for several datasets:

# ID 96: Nighttime Lights
include = /shared/sos/media/land/earth_night/nightlights/playlist.sos
rename =  夜間的地球
description = {{這個圖像由國家地球物理資料中心(NGDC)的防禦氣象衛星計畫DMSP)所紀錄下來的。國家地球物理資料中心的地球觀測團隊負責這些數據的研究與建檔,並將可利用的資料加以產品化。資料的蒐集則是利用每日繞行地球二次的極地軌道衛星,衛星有一個掃描線運轉系統,其可見光及近紅外光的(VNIR)感測器在夜間可做低度空間的監測,同時也可感測月光下的雲層、城鎮的燈光、工廠的區位,燃料氣的燃燒閃焰、火光、閃電和極光等。這些夜晚的光線資料都是防禦氣象衛星計畫在1994年10月到1995年3月之間蒐集的數據所建立起來的。

這張特別的圖像只顯示來自電力的光。海洋的部分以深藍色呈現,陸地則是以稍微淺一點的藍色來區分。所有的光都是明亮的白色。經濟繁榮或人口集中的區域通常光線較亮,大部分的海岸線附近也是高亮度地區,可見人們喜歡傍水而居。根據沿岸燈光可以勾勒出非洲尼羅河的輪廓。在美國,東半部地區人口密度比其他地區高。沿著燈光也可辨識重要高速公路之所在。

將全年的資料所合成的影像以及某一個夜晚的資料加以比較,就可以發現電力耗損的情形。全年所累積的光其影像是紅色的,特定一個夜晚的光則呈現綠色,該晚的溫度數據則以藍色呈現,因此雲層看起來是藍的。黃色代表一整年以及那個晚上都有亮光,綠色表示只亮那一晚;只有全年光影的則呈紅色。任何大範圍的紅色有可能就是電力耗損的區域。在卡崔納颶風侵襲過後的2005年8月30日,比較同一個地表不同時間拍攝的兩張影像可以看出災區的範圍;第一張是黑白的燈光影像,第二張有著色的照片則突顯一大片電力中斷的區域。 }}

# ID 44: Air Traffic
include = /shared/sos/media/atmosphere/air_traffic/playlist.sos
rename = 空中交通
description = {{每一天,在美國的天空都有87,000多的航班。其中1/3是航空公司,如西南航空。平均每天,空中交通管制員需要處理28,537的商業航班(其中包括全球跟地區航空公司),27,178通用航班(例如:私人飛機),24548空中租用航班(飛機租用),5,260班次的軍事飛行航班和2,148班次的遞送航班(聯邦快遞, UPS等)。在任何一個時段都有大約5,000航班在美國天空。一年裡,平均有6,400萬次的起飛和著陸。}}
Translating Dataset Playlists for a New Language
  1. Generate playlist files from the SOS dataset catalog using translations2db --generate_playlist (see the translations2db Command Line Utility section for details).
  2. 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.
  3. 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 or gedit. Be sure the description text is enclosed between {{ and }} characters
  4. 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

Editing 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.

Dataset Translation TSV Files

The second option for translating the names and descriptions of datasets and their variations is with tab separated value (tsv) files (see the Dataset Translation Playlists section for using the other option). 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. Here is an example of part of a zh_TW.tsv file imported to a Google Sheet, with translations of dataset names from column B to Traditional Chinese in column C:

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. Here is the Google Sheet in its completed form:

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).

Dataset Category and Keyword Translations

The 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. 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 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. Here is an example of portions of a Google Translated es_MX.csv file for Mexican Spanish:

      MajorCategory,Water,Agua
MajorCategory,Land,Tierra
MajorCategory,Space,Espacio
MajorCategory,Extras,Extras
MajorCategory,People,Gente
MajorCategory,Snow and Ice,Nieve y Hielo
MajorCategory,Air,Aire
MajorCategory,Site-Custom,Sitio-Aduana
SubCategory,Temperature,Temperatura
SubCategory,Real-time Weather Models,En tiempo real Tiempo Modelos
SubCategory,Health,Salud
Keyword,Phases,Fases
Keyword,Density,Densidad
Keyword,Sulfate,Sulfato
Translating Categories and Keywords for a New Language
  1. Create an en_US.csv file (see the translations2db Command Line Utility section for details).
  2. Rename it to the correct locale name following the xx_YY.csv naming convention
  3. Load it into a spreadsheet program (or a text editor if preferred)
  4. Replace the last column of English text with translated values. Do not modify the text in the first two columns.
  5. Export back to csv (if using a spreadsheet). Be sure the xx_YY.csv file is placed in the /shared/sos/locale/ directory.
  6. 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
  1. Load an existing xx_YY.csv file into a spreadsheet program (or a text editor if preferred)
  2. Update the last column of translated text with your edits. Do not modify the text in the first two columns.
  3. Export back to csv (if using a spreadsheet). Be sure the xx_YY.csv file is placed in the /shared/sos/locale/ directory.
  4. 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

The Remote App encompasses iPad and iPhone versions of the main controller of SOS for presenters. It has a rich user interface (UI) that includes many labels, buttons, and dialog boxes. The iPad and iPhone devices have the ability to set their 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 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 and iPhone Remote App UIs. 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. Here is an example of portions of a Google Translated es.tsv file for Mexican Spanish:

/* Main Interface */
Presentation ⇥ Entrega
Data Catalog Catálogo de datos
Playlist Builder ⇥ Generador de Lista de reproducción
Web Page ⇥ Página web
Settings ⇥ Ajustes
/* Presentation */
Annotate ⇥ Anotar
Zoom ⇥ Ampliar
Slices ⇥ Rebanadas
User Position ⇥ Posición de usuario
Show ⇥ Mostrar
Hide ⇥ Esconder
Slicer ⇥ Divisor
^Split Sphere ⇥ Acerca de dividir la esfera en varios sectores. Por favor espera...
^Position Info ⇥ Ajustes de orientación se producen en relación con esta posición de visión longitudinal situado en el ecuador.
^Frame Info ⇥ Utilice el control deslizante del marco para desplazarse a un fotograma deseado en el conjunto de datos.
^Playlist Button ⇥ Lista de reproducción
^Catalog Button ⇥ Catálogo
Volume ⇥ Volumen
^Volume Info ⇥ Los ajustes de volumen ocurren en relación con el volumen en el equipo SOS

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. The symbol "⇥" shown in the example is actually a tab character. 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

  1. Copy the en.tsv file in /shared/sos/locale/iOS to the correct locale name following the xx.tsv naming convention (contact SOS Support to obtain this file if it is not already on your system).
  2. Load it into a spreadsheet program such as Google Sheets (or a text editor if preferred)
  3. 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).
  4. Export back to tsv (if using a spreadsheet). Be sure the xx.tsv file is placed in the /shared/sos/locale/iOS/ directory.
  5. 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

  1. Load the xx.tsv file in /shared/sos/locale/iOS into a spreadsheet program such as Google Sheets (or a text editor if preferred)
  2. Update the last column of translated text with your edits. Do not modify the text in the first column.
  3. Export back to tsv (if using a spreadsheet). Be sure the xx.tsv file is placed in the /shared/sos/locale/iOS/ directory.
  4. 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

In order for the Remote App to use translations, the iPad or iPhone 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 on an iPhone to German in Germany:

  1. Set the Region to Germany (DE)

  2. 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.

Below is an example of part of the Remote App translated to Traditional Chinese. Note that the Remote App base interface must be changed to Traditional Chinese for the translations to appear. This example also shows some of the datasets translated in addition to the UI translations.



Public Kiosk Translations

In 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

  1. Public UI text translations are created and edited using the Language tab in the Admin UI on the Windows kiosk machine. 
  2. 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

  1. Kiosk dataset names and descriptions are translated using the SOS Data Catalog and playlists as described in the Kiosk Dataset Translations section.
  2. 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

The 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:

  1. 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.
  2. 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.
  3. 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 a way to override the Data Catalog text.

  • English sample:

For reference, here is a portion of the en_US.sos playlist for datasets, which includes two datasets:

# ID 3: Hurricane Season - 2005
include = /shared/sos/media/atmosphere/2005_hurricane/grayir/playlist.sos
rename = Hurricane Season - 2005
description = {{The 2005 hurricane season shattered records that have stood for decades - most named storms, most hurricanes and most category five storms. With 28 named storms, 15 hurricanes, seven major hurricanes, and four category 5 hurricanes, the 2005 hurricane season certainly blew the records away. It was also the first season in which four major hurricanes hit the U.S.. Even with all these records, the 2005 hurricane season will arguably be most remembered for Hurricane Katrina, which devastated parts of Mississippi, Louisiana and in particular, New Orleans.

This dataset is a gray-scale infrared satellite image available from June 1, 2005 through January 3, 2006.}}

# ID 82: Blue Marble
include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos
rename = Blue Marble
description = {{The Blue Marble is an incredibly detailed, true-color depiction of the Earth. NASA is responsible for this dataset made from a compilation of satellite images throughout 2001. The background image of the land and oceans was created using data from June through September of 2001. This could not be done in a single day or even a week because on any given day clouds are blocking a significant portion of the surface. The cloud image is a composite of three days worth of data. The shading is true color with the oceans shades of blue, the clouds white and the lands varying from green to brown. The brown areas are the sands of the deserts.}}

Each of the two datasets shown uses three playlist keywords that are applicable to translations:

    include = path to the dataset playlist
    rename = kiosk name for the dataset
    description = 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:

For example, here are the same two datasets in Traditional Chinese from the translation playlist /shared/sos/kiosk/playlists/locale/datasets/zh_TW.sos:

include = /shared/sos/media/atmosphere/2005_hurricane/grayir/playlist.sos
rename = 2005年颶風季節
description = {{2005年的颶風季節打破了多項記錄,例如颶風最高等級5。總共有28個被命名的風暴,15個颶風,7個極大的颶風,和4個5級颶風。其中最強的是是卡催娜颶風,這個颶風摧毀了密西西比州,路易斯安那州,其中新奧爾良地區超過1600人在風暴中喪生,估計全部損失超過750億美元。}}

include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos
rename = 地球-藍色星球
description = {{這顆藍色星球非常詳盡而真實地描繪地球的面貌,這個資料集是由美國太空總署編輯2001年一整年的人造衛星影像所建立起來的。 大部分的訊息來自美國太空總署的輻射光譜影像分析器 MODIS(the Moderate Resolution Imaging Spectroradiometer),它架設在地球上方 435 英里的特拉這顆人造衛星上。陸地與海洋的背景影像是採用從 2001年 6 月至 9 月的所有資料所建立起來的,而不是採用某一天或一個禮拜的資料,因為任何一天,都會有雲層擋住地表某些特定的區域。雲的影像是由資料值所合成的,前二天收集的是可見光波的資料,第三天為了得到極地地區雲層的景觀所採用的是紅外線熱能影像。
海洋的藍色是原本真實的顏色,雲是白色,陸地從綠色到棕色有不同顏色的變化。棕色的部分是沙漠的沙地,編輯陸地影像的資料來自美國地球資源調查地質測量報告和科學資料中心。
其它有關藍色星球的數據,則用來強化地球變化的一些特徵。標準的藍色星球是地球全年平均數據所呈現的景觀。也可根據每個月的資料合成全年的數據圖像,而沒有雲層覆蓋。每個月的變化呈現具有季節性的藍色星球。每個月的演變讓觀眾到地貌的季節性變化。最讓人驚豔的是白雪在冬季逐漸漫天蓋地及在夏季消融的景像。藍色星球也因為沒有雲層的遮蔽,才能清楚看到地表的植被。}}

  • How to edit translations:

Editing 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:

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:

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:

After 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

The 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:

  1. 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.
  2. 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:

# popular group
include = /shared/sos/kiosk/playlists/groups/popular.sos
rename = 最受歡迎

# air group
include = /shared/sos/kiosk/playlists/groups/air.sos
rename = 大氣

# water group
include = /shared/sos/kiosk/playlists/groups/water.sos
rename = 水文

# land group
include = /shared/sos/kiosk/playlists/groups/land.sos
rename = 地表

# snow_and_ice group
include = /shared/sos/kiosk/playlists/groups/snow_and_ice.sos
rename = 冰雪

# space group
include = /shared/sos/kiosk/playlists/groups/space.sos
rename = 太空

# people group
include = /shared/sos/kiosk/playlists/groups/people.sos
rename = 人文

After finishing your translation changes, run media2kiosk, then transfer the resulting files to the kiosk machine using the FTP tab in the Admin UI.

Here is an example with the Public Kiosk UI translated to Traditional Chinese, along with the kiosk datasets and groups:


Admin UI Translations

The 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
  1. If it is running, close the kiosk application on the Windows machine.
  2. 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.
  3. From the menu bar, select File > Open... 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.


  4. From the menu bar, select File > Save 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.
  5. From the menu bar, select Edit > Translation 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.
  6. 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.
  7. 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.
  8. From the menu bar, select File > Save to save your translations to the raw translations file.
  9. From the menu bar, select File > Release to write your translations to the compiled (binary) translations file.
  10. 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.

Here is an example with the Viewpoint tab of the Admin UI translated to Traditional Chinese:



Visual Playlist Editor Translations

The 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.

  1. 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.
  2. 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.
  3. 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.

  4. 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).
  5. 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 form xx_YY.tsv will be created, including the fr_FR.ts example here.
  6. 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.
  7. From the menu bar, select File > Open 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 Edit > Translation File Settings… In the Settings dialog box, fill in the Target language information for your new locale and press OK.

  8. 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.
  9. 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.
  10. From the menu bar, select File > Save to save your translations to the raw translations ts file (fr_FR.ts in this example).
  11. From the menu bar, select File > Release to write your translations to the compiled (binary) translations file. In this example, the file will be named fr_FR.qm.
  12. You are now ready to test your translations. When you run the VPLE, from the menu bar, select the Language > franç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.

Here is an example with the VPLE UI in Presentation mode translated to Traditional Chinese, along with the SOS Data Catalog:

Here is another example with the VPLE UI in Dataset mode with the Text PIP editor translated to Spanish (generated using Google Translate):


Performing Translations using the SOS Stream GUI

The 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


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



There are four translation items in the Utilities menu.

  • 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… 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… 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… 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 Command Line Utility

All 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.

The --help option lists all the valid options and their purpose (which have been reformatted and augmented here in a table format for clarity):

Option Description
--load_playlists

Use 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

Use 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

Use to load category and keyword translations.

Loads translations for major categories, subcategories, 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.

May be used together with either the --load_playlists or --load_dataset_tsv options (but not both at once).

--remove_all

Use to clear all data-related translations loaded previously.

Removes all translations of dataset names & descriptions, major & sub 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

Use 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

Use 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

Use 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

Use 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

Use 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

Use 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.

--verbose

Used for troubleshooting.

Write timestamps with logged messages (must appear before --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 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

Used for troubleshooting.

Use an alternate database in the --root directory copied from /shared/sos/database. Do not use for the iPad!

--generate_sosx_tsv

For 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.