Data localization and translation

Data Localization and Translation

Data Localizationand

Translation

Yevhen [email protected]

https://github.com/yshyshkin

mailto:[email protected]

mailto:[email protected]




Language localisation is the process of adapting a product that has been previously translated into different languages to a specific country or region.

What is language localization?


Where localization is applied?- Name formatting- Address formatting- Datetime formatting- Number formatting

- Decimal- Integer- Percent- Currency


Localization configurationSystem > Configuration > Localization


Localization configuration$this->get('oro_locale.settings')->getLocale();$this->get('oro_locale.settings')->getCurrency();

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Model/LocaleSettings.phphttps://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/public/js/locale-

settings.js

Result: enUSD

PHP:

JS: require(['orolocale/js/locale-settings'],function(localeSettings) { localeSettings.getLocale(); localeSettings.getCurrency();});

Twig: {{ oro_locale() }}{{ oro_currency() }}

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Model/LocaleSettings.php

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Model/LocaleSettings.php

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/public/js/locale-settings.js




Name formatting- Names are formatted based on locale- Name format configuration can be defined in any

bundle’s YAML file Resources/config/oro/name_format.yml

- Format may contain placeholders for name prefix, name suffix, first name, last name and middle name

- Entity must include Oro\Bundle\LocaleBundle\Model\FullNameInterface

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Model/FullNameInterface.php




Name formatting

en: %prefix% %first_name% %middle_name% %last_name% %suffix% en_US: %prefix% %first_name% %middle_name% %last_name% %suffix% ru: %last_name% %first_name% %middle_name% ru_RU: %last_name% %first_name% %middle_name%

Configuration example

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/config/oro/name_format.yml





Name formatting$user = new User(); // implements FullNameInterface$user->setNamePrefix('Mr.') ->setFirstName('John') ->setMiddleName('S.') ->setLastName('Doe') ->setNameSuffix('Jr.'); $this->get('oro_locale.formatter.name')->format($user);$this->get('oro_locale.formatter.name')->format($user, 'ru');

PHP:

Twig: {{ entity|oro_format_name }}{{ entity|oro_format_name('ru') }}

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Formatter/NameFormatter.php




Name formattingrequire(['orolocale/js/formatter/name'],function(nameFormatter) { var user = { 'prefix': 'Mr.', 'first_name': 'John', 'middle_name': 'S.', 'last_name': 'Doe', 'suffix': 'Jr' }; nameFormatter.format(user); nameFormatter.format(user, 'ru');});

JS:

Result: Mr. John S. Doe Jr.Doe John S.

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/public/js/formatter/name.js





Address formatting- Addresses are formatted based on primary

location or country address - Address format configuration can be defined in

any bundle’s YAML file Resources/config/oro/address_format.yml

- Format may contain placeholders for name, organization, street, city, region, region code, country, country code and postal code

- Entity must include Oro\Bundle\LocaleBundle\Model\AddressInterface

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Model/AddressInterface.php




Address formatting

US: format: '%name%\n%organization%\n%street%\n%CITY% %REGION_CODE% %COUNTRY_ISO2% %postal_code%' require: [street, city, region, postal_code] zip_name_type: zip region_name_type: region

RU: format: '%postal_code% %COUNTRY% %CITY%\n%STREET%\n%organization%\n%name%' require: [street, city, postal_code]

Configuration example

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/config/oro/address_format.yml





Address formatting$country = new Country('US');$country->setName('United States of America') ->setIso3Code('USA');

$region = new Region('US-CA');$region->setCode('CA') ->setName('California');

$address = new Address(); // implements AddressInterface$address->setNamePrefix('Mr.') ->setFirstName('John') ->setMiddleName('S.') ->setLastName('Doe') ->setNameSuffix('Jr.');$address->setStreet('Random str., 3, 14') ->setCity('Los Angeles') ->setRegion($region) ->setCountry($country) ->setPostalCode('12345') ->setOrganization('Oro Inc.');

$this->get('oro_locale.formatter.address')->format($address);

PHP:


Address formattingTwig: {{ address|oro_format_address|nl2br }}

require(['orolocale/js/formatter/address'],function(addressFormatter) { var address = { 'prefix': 'Mr.', 'first_name': 'John', 'middle_name': 'S.', 'last_name': 'Doe', 'suffix': 'Jr', 'organization': 'Oro Inc.', 'street': 'Random str., 3, 14', 'city': 'Los Angeles', 'region_code': 'CA', 'country_iso2': 'US', 'postal_code': '12345' }; addressFormatter.format(address);});

JS:


Address formattingResult: Mr. John S. Doe Jr.

Oro Inc.Random str., 3, 14LOS ANGELES CA US 12345

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Formatter/AddressFormatter.phphttps://github.com/orocrm/platform/blob/1.6.0

/src/Oro/Bundle/LocaleBundle/Resources/public/js/formatter/address.js

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Formatter/AddressFormatter.php

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Formatter/AddressFormatter.php

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/public/js/formatter/address.js




Datetime formatting- Datetime values are formatted based on locale,

timezone and type (none, short, medium, long, full)

- Datetime format configuration extracted from libicu via PHP INTL extension

- Datetime formatter accepts \DateTime object, string and timestamp values


Datetime formattingPHP: $dateTime = new \DateTime(

'2011-12-13 14:15:16', new \DateTimeZone('UTC'));$formatter = $this->get('oro_locale.formatter.date_time');$formatter->format($dateTime);$formatter->formatDate($dateTime->format('Y-m-d'));$formatter->formatTime($dateTime->getTimestamp());

Result: Dec 13, 2011 4:15 PMDec 13, 20114:15 PM

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Formatter/DateTimeFormatter.php




Datetime formatting

JS: require(['orolocale/js/formatter/datetime'],function(datetimeFormatter) { datetimeFormatter.formatDateTime('2011-12-13T14:15:16+0000'); datetimeFormatter.formatDate('2011-12-13'); datetimeFormatter.formatTime('14:15:16');});

Twig: {{ '2011-12-13 14:15:16'|oro_format_datetime }}{{ '2011-12-13'|oro_format_date }}{{ '14:15:16'|oro_format_time }}

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/public/js/formatter/datetime.js

Result: Dec 13, 2011 4:15 PMDec 13, 20112:15 PM





Datetime format handling- Different libraries use different datetime formats- Oro Platform provides format converters for

libicu, moment.js and jquery.ui- New formatters can be registered using DI tag

oro_locale.format_converter.date_time


Datetime timezone handling- To simplify timezone handling all \DateTime

object in the backend should be in UTC timezone

- \DateTime objects saved to the DB and extracted from the DB are automatically converted to UTC timezone

- Formatting of \DateTime objects should be performed using DateTimeConverter via service oro_locale.formatter.date_time


Number formatting- Numbers are formatted based on locale- Formatter works with decimal, percent, currency,

spellout, duration and ordinal values- Number format configuration extracted from

libicu via PHP INTL extension- Currency use symbols from YAML files

Resources/config/oro/currency_data.yml


Number formatting$formatter = $this->get('oro_locale.formatter.number');$formatter->formatDecimal(12345.6789);$formatter->formatDecimal(12345);$formatter->formatPercent(1.2345);$formatter->formatCurrency(12345.6789);$formatter->formatCurrency(12345.6789, 'EUR');

PHP:

Twig: {{ 12345.6789|oro_format_decimal }}{{ 12345|oro_format_decimal }}{{ 1.2345|oro_format_percent }}{{ 12345.6789|oro_format_currency }}{{ 12345.6789|oro_format_currency({'currency':'EUR'}) }}

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Formatter/NumberFormatter.php




Number formattingrequire(['orolocale/js/formatter/number'],function(numberFormatter) { numberFormatter.formatDecimal(12345.6789); numberFormatter.formatInteger(12345); numberFormatter.formatPercent(1.2345); numberFormatter.formatCurrency(12345.6789); numberFormatter.formatCurrency(12345.6789, 'EUR');});

JS:

Result: 12,345.67912,345123.45%$12,345.68€12,345.68

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/LocaleBundle/Resources/public/js/formatter/number.js





Localization CLI commandsoro:localization:dump - dump localization configuration from YAML files to web/js/oro.locale_data.js


Translation is the communication of the meaning of a source-language text by means of an equivalent target-language text.

What is translation?


Oro Platform use standard Symfony2 mechanism to perform frontend translation in PHP, in Twig templates, and translator.js library from BazingaJsTranslationBundle

Translations are stored in YAML files in any bundle and in the application database.

How translations used in Oro Platform?


- messages - common messages used both for system and custom purposes

- validators - validation messages- jsmessages - messages translated on frontend

side- tooltips - messages for and form field tooltips- entity - data for entities translated with Gedmo

translatable extension

Translation domains


Recommendedtranslation message format

<application>.<bundle>.<section>.<key>

oro.user.form.choose_genderoro.dataaudit.change_history.titleoro.entity_config.menu.entities_list.label

Format:

Examples:


Translation extractors- PhpCodeExtractor - extracts formatted

strings from PHP code- NavigationTranslationExtractor -

extracts title translations from navigation.yml files

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/TranslationBundle/Extractor/PhpCodeExtractor.php

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/NavigationBundle/Title/TranslationExtractor.php








Translation on backend

$this->get('translator')->trans('oro.dashboard.title.main');$this->get('translator')->trans('oro.entity.item', ['%id%' => 42]);

PHP:

Twig: {{ 'oro.dashboard.title.main'|trans }}{{ 'oro.entity.item'|trans({'%id%': 42}) }}

Result: DashboardItem #42

# messages.en.ymloro.dashboard.title.main: "Dashboard"oro.entity.item: "Item #%id%"

YAML:


Translation on frontend

require(['orotranslation/js/translator'],function(__) { __('oro.note.add_note_title'); __('oro.datagrid.pagination.totalRecords', {totalRecords: 42});});

JS:

Result: Add noteTotal of 42 records

# jsmessages.en.ymloro.note.add_note_title: "Add note"oro.datagrid.pagination: totalRecords: "Total of {{ totalRecords }} records"

YAML:


Translation in the database- table oro_translation- entity OroTranslationBundle:Translation- scopes SYSTEM and UI

# id# key# value# locale# domain# scope

Translation


Translation in database- OrmTranslationLoader - loads

translations from database- DatabasePersister - persists translations

to database

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/TranslationBundle/Translation/OrmTranslationLoader.php

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/TranslationBundle/Translation/DatabasePersister.php








Translation configurationSystem > Configuration > Language settings


Interaction with Crowdin- Dump translations from translation extractors

and YAML files- Download translations from Crowdin- Merge them with existing translations- Upload updated translations to Crowdin

Oro Platform Crowdin

1. dump 2. download

3. merge

4. upload


Debug translator- Wraps translated strings in square brackets -

[<string>]- Wraps not translated strings into exclamation

marks - !!!---string---!!!- Add JS prefix for frontend translations- can be enabled in app/config/config.yml

oro_translation: debug_translator: true

https://github.com/orocrm/platform/blob/1.6.0/src/Oro/Bundle/TranslationBundle/Translation/DebugTranslator.php





Debug translator


Translation CLI commandsoro:translation:dump - dumps frontend translations into web/js/translation/<locale>.jsoro:translation:pack - extracts translation files for each bundle in specified vendor namespace and creates language pack


Questionsand

Answers

Documents

Data localization and translation