/
Stratus internationalization: adding a language

Stratus internationalization: adding a language

Owned by Andriy Fomenko (Unlicensed)
Sept 18, 2018


Stratus internationalization language support


Abstract: This document describes the utilities for internationalization / language support embedded into Stratus and the procedures to perform additions of new languages, and corrections of constants for existing languages.


Applicability: Stratus 3.9.15+ codebase


Intended audience: Software Engineers,Translators, Quality Assurance Engineers


Skills and tools required:

  • Translation files editor: “Poedit” editor may be obtained from http://poedit.net/
  • SCP: utility for “secure copy”, may be used from any distribution like PuTTY, CygWin; CygWin distribution was used in examples; it will be used mostly by Localization  Engineers working on and relevant parts of this instruction will be highlighted in green
  • SSH and BASH: utilities to support secure remote shell on the system where Localization is getting developed, it will be used mostly by Software Developer and highlighted in red


- - -


First , the following is a generic overview on performing the localization add/modify process:


  1. Software Engineer[s] must install the latest version of the Stratus application software on a “development system” AND grant access to the Translator[s] performing Localization
  2. The translator receives system URI and access credentials for SCP access from Software Engineer
  3. Translator downloads translation files (details follow below) to his local PC and adds/edits definitions in Poeditor software
  4. Translator uploads changed files to the development system, runs locale files update with supplied utilities (details follow below)
  5. Translator and/or Quality Assurance Engineer[s] open application in the browser, select language under development and perform review, navigating through the application screens to identify any language constants that still require changes
  6. Translator updates Items identified as missing or requiring correction in Poeditor, and the cycle repeats from step 5
  7. Once Translator[s] and/or Quality Assurance Engineer[s] obtain satisfactory results, Software Engineer[s] identify a list of files which underwent modification and incorporate the updated versions of these files into the software code repository
  8. A new, formal “internal” Stratus version must be built to deliver the updates
  9. The updated Stratus must be installed on the “development system”, after which steps 6-9 are repeated until no more changes are needed
  10. The final “production” Stratus version must be built to make a General Availability distribution for software end-users


After this generic process description, detailed instructions and samples follow below:


#1. Stratus system preparation for localization updates


  1. Install standard Stratus distribution of the latest version


  1. Create an additional user for Translator[s] to access (from root account):


# adduser i18n -G wheel,apache

# passwd i18n


  1. Provide additional permissions for the files to be modified


# chmod -R g+w /opt/sarch/conf/etc/locale

# chmod -R g+w /opt/sarch/sdi/html/locale

# chmod g+w /opt/sarch/api/lib/php/i18n.php /opt/sarch/conf/bin/locale/make_locale


  1. Check that locale files can be [re]compiled


# /opt/sarch/conf/bin/locale/make_locale



#2. Translator to check login/permissions provided to do his[er] job


  1. Log in with credentials given to you using “ssh” remote access utility,
  2. then execute “sudo -i” to confirm you are given permissions to escalate privileges,
  3. then hit Ctrl-D twice to logout from privileged shell and then from regular shell:


C:\DEV\>ssh i18n@demo-6

i18n@demo-6's password: xxxxxxx

Last login: Thu Jan 14 14:20:14 2016 from 192.168.17.134

[i18n@demo-6 ~]$ sudo -i

[root@demo-6 ~]# logout

[i18n@demo-6 ~]$ logout

Connection to demo-6 closed.



#3. Download localization definition files to workstation


This is an optional sub-step if you are about to incorporate any additional language definition[s].


You can skip up to “Download .po-files” if you only plan to edit existing language[s].


To add language[s], connect to the server with “ssh” utility and add language[s] using the following procedure:


C:\DEV\Locale>ssh i18n@demo-6

i18n@demo-6's password: xxxxxxx

Last login: Thu Jan 14 15:13:38 2016 from 192.168.17.134

[i18n@demo-6 ~]$ sudo -i

[root@demo-6 ~]# vi /opt/sarch/api/lib/php/i18n.php


Scroll to the very end of file and add new language type (here it is it_IT / Italian):


             "it_IT" => array(

                      "name" => "Italian",

                      "direction" => "rtl"

)


You must also register this additional language into locale generation script:


[root@demo-6 ~]# vi /opt/sarch/conf/bin/locale/make_locale


Scroll to the very end of file and add new language type (here it is it_IT / Italian):


createLocale "it_IT" "Italian"


At this point, you would must re-generate .po files:


[root@demo-6 ~]# mkdir -p /opt/sarch/conf/etc/locale/it_IT/LC_MESSAGES

[root@demo-6 ~]# /opt/sarch/conf/bin/locale/make_locale


Hit “Ctrl-D” twice to exit remote shell session.


Download .po-files. In this example, the download is executed with “scp” utility, which is part of CygWin package, files are placed into current shell directory, which is “C:\DEV\Locale”:


C:\DEV\Locale>scp -r i18n@demo-6.videonext.com:/opt/sarch/conf/etc/locale .

i18n@demo-6.videonext.com's password: xxxxx

admin.mo                                              100% 129KB 128.6KB/s 00:01

admin.po                                              100% 377KB 377.3KB/s 00:00

admin.mo                                              100% 427 0.4KB/s 00:00

admin.po                                              100% 286KB 285.9KB/s 00:00

admin.mo                                              100% 129KB 128.7KB/s 00:00

admin.po                                              100% 388KB 387.8KB/s 00:00

admin.mo                                              100% 157KB 156.7KB/s 00:00

admin.po                                              100% 429KB 429.0KB/s 00:00


As a result, a set of sub-directories containing all present language definitions will be copied to local disk of your workstation:


C:\DEV\Locale>dir locale/*/*

locale/ar_AE/LC_MESSAGES:

admin.mo  admin.po

...

locale/it_IT/LC_MESSAGES:

admin.mo  admin.po


At this point, you can use Poedit localization editor to edit text constants. For example, Italian definitions will be located in locale/it_IT/LC_MESSAGES/admin.po file.



#4. Uploading updated language files back to development server


Once language definitions are updated in Poedit software, it is time to push it back to development server and perform a preview/review of the translation results.


This step involves using “scp” utility to copy files from Windows PC to the server, the using “ssh” to trigger language definition recompilation, which adopts it to the format suitable for Stratus software.


Please make sure your Windows shell current directory is where it used to be when you performed copy from the server to your PC. Examples in this instruction were using C:\DEV\Locale as such directory. First command in next example specifically confirms presence of “locale” subdirectory inside to make sure everything is in order.


Here is how the copy process appears:


C:\DEV\Locale>dir

locale


C:\DEV\Locale>scp -r locale i18n@demo-6.videonext.com:/opt/sarch/conf/etc/locale

i18n@demo-6.videonext.com's password: xxxxxxxx

admin.mo                                              100% 129KB 128.6KB/s 00:00

[...]

admin.po                                              100% 429KB 429.0KB/s 00:00


Here is the step to perform definition update (using remote session with “ssh” utility):


C:\DEV\Locale>ssh i18n@demo-6

i18n@demo-6's password: xxxxxxx

Last login: Thu Jan 14 14:20:14 2016 from 192.168.17.134

[i18n@demo-6 ~]$ sudo -i

[root@demo-6 ~]# /opt/sarch/conf/bin/locale/make_locale


Please check for any warning[s] or error[s], as these may indicate a problem in the supplied definitions and/or recompilation process.


Once your definitions were compiled, you can hit “Ctrl-D” twice to exit the remote shell.



#5. Localization results review


The next logical step in the process is to perform visual localization update[s] review.


First of all, a word of caution is in order on the “caching”, which is an integral part of the Web, but may lead to unpredictable results when working on short update-review-repeat cycle with Stratus WebUIs.


Basically, the problem is that it may take some time for your PC browser cache to be “flushed”, and it may lead to confusions like “I know I edited this text constant, but I still see old definition”.


To avoid this, at the least, a cache cleanup may need to be performed every time definitions are updated, or [better], you can temporarily disable caching and make browser to reload web-resources every time it visit the page, as follows:


Here you must open Settings, then open dialog in Browsing History -> Settings, set “Every visit to the page”.

Now, login to the application, making sure to select the language you want to review:



After this, navigate through all application screens, specifically noting textual constants, which are missing or that require additional corrections.



#6. Identifying missing and/or wrong text constants


Some problems you may typically encounter are:


  • Problem: Text constant is still showing up in English
    Solution: Translation is missing in PO-file, so look for this exact line, noting that some messages might have slight variations (like in uppercase/lowercase)
  • Problem: Text is translated as defined in PO-file, but does not fit container on the screen
    Solution: Try rephrasing translation to make it shorter


You must incorporate fixes to the problems identified into .po-file[s] and repeat upload/compile/review process until you get a satisfactory result.



#7. Incorporating updates into formal Stratus software build[s]


The Configuration Manager must copy the following files from the development system into software code repository before performing a formal software rebuild:


[root@demo-6 ~]# ll /opt/sarch/api/lib/php/i18n.php

-rw-r----- 1 root apache 2137 Jan 14 15:58 /opt/sarch/api/lib/php/i18n.php

[root@demo-6 ~]# ll /opt/sarch/conf/bin/locale/make_locale

-rwxr-x--- 1 root apache 4713 Jan 14 15:49 /opt/sarch/conf/bin/locale/make_locale

[root@demo-6 ~]# ll /opt/sarch/conf/etc/locale

total 0

drwxrwx--- 3 root apache 24 Jan 14 14:24 ar_AE

drwxrwx--- 3 root apache 24 Jan 14 14:24 en_US

drwxrwx--- 3 root apache 24 Jan 14 14:24 es_ES

drwxr-xr-x 3 root root   24 Jan 14 16:01 it_IT

drwxrwx--- 7 i18n i18n   66 Jan 14 16:23 locale

drwxrwx--- 3 root apache 24 Jan 14 14:24 ru_RU

[root@demo-6 ~]# ll /opt/sarch/sdi/html/locale

total 1400

-rw-rw---- 1 root apache 310812 Jan 14 16:01 ar_AE.json

-rw-rw---- 1 root apache 210355 Jan 14 16:01 en_US.json

-rw-rw---- 1 root apache 325866 Jan 14 16:01 es_ES.json

-rw-r--r-- 1 root root   210856 Jan 14 16:01 it_IT.json

-rw-rw---- 1 root apache 368028 Jan 14 16:01 ru_RU.json



#8. Releasing an updated Stratus software version into production


Formal QA change control must be performed before approving a rebuilt software package for usage in production.




Further information and assistance


Please register at http://help.videonext.com (unless you have an account there already) to open Support Tickets.


You may also create Support Ticket by sending your issue description over email to support@videonext.com.


Please make sure your issue report incorporates a detailed problem description such as “what I expected to see vs. what I see in reality.”  This will help videoNEXT to help you in efficient manner!


Thank you!