SOS Translation Guide

Introduction

Beginning with the 5.0 release, multi-language support is 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.

The iOS Remote App (“iPad App”) and the new NOAA SOS Public Kiosk (“NOAA Kiosk”) are the first applications to include localized user interfaces, which includes dynamic translation of text in labels, buttons, and dialog boxes to a native language. The SOS Data Catalog also now supports localization of dataset names and descriptions, major and sub categories, and keywords, including language variations in different countries. Going forward, other SOS software will build upon this foundation.

In most cases, NOAA will not be creating localizations 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.

Overview

There are two principal types of localizations done in SOS: 1) datasets and related metadata, and 2) user interfaces in specific applications. Dataset translations in SOS are accomplished in two ways: 1) Dataset names and descriptions are translated by using playlists, and 2) related metadata including major category, subcategory, and keywords are translated using comma separated value (csv) files, which are easily imported to and exported from spreadsheets, such as Excel and Google Sheets.

User interface translations are handled differently depending on the technology used. For the iPad and iPhone, translations are defined using tab separated value (tsv) files, another common import/export format for spreadsheets. For the NOAA Kiosk, there is minimal text to translate and those are handled with simple property-value text files. The kiosk also does its own dataset name and description translations separate from the SOS Data Catalog, since a site may wish to show different text to the general public. However, the same playlists used to do dataset translations could be used in both the kiosk and the SOS Data Catalog. For more information on localization in the NOAA Kiosk, see the NOAA SOS Public Kiosk guide. For general assistance on performing translations for SOS, please contact SOS support at sos.gsd@noaa.gov.

Dataset Translations

Translation playlists reside on the SOS machine under the /shared/sos/locale directory. Each playlist follows the naming convention xx_YY.sos, 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.sos playlist is present, it will not imported into the SOS Data Catalog since American English values are already defined by default. 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.

Each dataset is specified by an include keyword with the dataset playlist path, a rename keyword with a translated name, and a description keyword 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萬次的起飛和著陸。}}

To set up a new translation of dataset names and description from scratch, follow the following steps:

  1. Create an en_US.sos file (see the Translations2db Command Line Utility section for details)
  2. Rename it to the correct locale name following the xx_YY.sos naming convention
  3. Replace the English values for the rename and description keywords with translated values in a Linux text editor, such as vi or gedit.
  4. Be sure the xx_YY.sos file is placed in the /shared/sos/locale/ directory.
  5. Load the xx_YY.sos file into the SOS Data Catalog using either the SOS Stream GUI or command line utility (described in later sections)

The SOS Data Catalog uses metadata 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

To set up a new translation for dataset-related metadata from scratch, follow the following steps:

  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 command line utility (described in later sections)

iOS Remote App User Interface Translations

The iOS Remote App encompasses iPad and iOS versions of the main controller of SOS for presenters. It has a rich user interface that includes many labels, buttons, and dialog boxes. The iPad and iPhone devices have the ability to set their Language and Country from Settings, 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 iOS 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 iOS 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 was chosen instead of csv here because commas frequently occur in the iOS user interface 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 iOS translations). The default locale is en, which is English. Unlike 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 user interfaces. This is unlikely to be used routinely, but is available to anyone wishing to do some minor customization of the iOS 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.

To set up a new translation for the iOS user interface text from scratch, follow the following steps:

  1. Copy the en.tsv file in /shared/sos/locale to the correct locale name following the xx.tsv naming convention
  2. Load it into a spreadsheet program ( 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.
  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 command line utility (described in later sections)

Performing Translations in the SOS Stream GUI

The SOS Stream GUI provides 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 called translations2db with different options (described in the next section). The menu items provide convenience access to the most commonly used translation operations.

From the Library menu:


  • Perform Translations… reruns all the translation operations for datasets, related metadata, and iOS UI. This should be used any time the Update Library… item has been called, because that operation clears all the translations from the Data Catalog.
From the 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_YY.tsv) in /shared/sos/locale/iOS and converts them into xx_YY.strings files. This command is useful when adding user interface translations to see how they appear in the iPad or iPhone. 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 called by a menu item in the SOS Stream GUI or directly on the command line. There are a number of options, all of which begin with “--”. Multiple options may 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 for clarity):

$ translations2db --help
Usage:
--load_playlists
load dataset translations from playlists into data catalog

--load_csv
load category/keyword translations from comma separated value (csv) files into data catalog

--remove_all
remove all datasets/category/keyword translations from data catalog

--verbose
verbose mode (show conversion details)

--root directory
use a different translations root directory (default is /shared/sos/locale)
Used primarily for testing.

--tsv_to_ios_strings
convert iOS remote app translations from tab separated value (tsv) files to iOS strings files

--generate_playlist
create playlist for datasets in English from data catalog
Useful for creating a starting point for translating dataset names and descriptions from American English into a new language.
The output file is /shared/sos/locale/en_US.sos.


--generate_csv
create comma separated value (csv) file for categories/keywords in English from data catalog
Useful for creating a starting point for translating major category, subcategory, and keywords from American English into a new language.
The output file is /shared/sos/locale/en_US.csv.