Data Localization and Translation

Data Localization

and

Translation

Yevhen Shyshkinyshyshkin@orocrm.com

https://github.com/yshyshkin

Data Localization and Translation

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?

Data Localization and Translation

Where localization is applied?

- Name formatting

- Address formatting

- Datetime formatting

- Number formatting

- Decimal

- Integer

- Percent

- Currency

Data Localization and Translation

Localization configurationSystem > Configuration > Localization

Data Localization and Translation

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

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

settings.js

Result: en

USD

PHP:

JS: require(['orolocale/js/locale-settings'],

function(localeSettings) {

localeSettings.getLocale();

localeSettings.getCurrency();

});

Twig: {{ oro_locale() }}

{{ oro_currency() }}

Data Localization and Translation

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

Data Localization and Translation

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/na

me_format.yml

Data Localization and Translation

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

Data Localization and Translation

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/na

me.js

Data Localization and Translation

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

Data Localization and Translation

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/ad

dress_format.yml

Data Localization and Translation

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:

Data Localization and Translation

Address formatting

Twig: {{ 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:

Data Localization and Translation

Address formatting

Result: Mr. John S. Doe Jr.

Oro Inc.

Random str., 3, 14

LOS ANGELES CA US 12345

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/addr

ess.js

Data Localization and Translation

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

Data Localization and Translation

Datetime formatting

PHP: $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 PM

Dec 13, 2011

4:15 PM

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

Data Localization and Translation

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/da

tetime.js

Result: Dec 13, 2011 4:15 PM

Dec 13, 2011

2:15 PM

Data Localization and Translation

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

Data Localization and Translation

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

Data Localization and Translation

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

Data Localization and Translation

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

Data Localization and Translation

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

12,345

123.45%

$12,345.68

€12,345.68

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

mber.js

Data Localization and Translation

Localization CLI commands

oro:localization:dump - dump localization

configuration from YAML files to

web/js/oro.locale_data.js

Data Localization and Translation

Translation is the communication of the

meaning of a source-language text by

means of an equivalent target-language text.

What is translation?

Data Localization and 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?

Data Localization and Translation

- 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

Data Localization and Translation

Recommendedtranslation message format

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

oro.user.form.choose_gender

oro.dataaudit.change_history.title

oro.entity_config.menu.entities_list.label

Format:

Examples:

Data Localization and Translation

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/PhpCodeEx

tractor.php

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

tor.php

Data Localization and Translation

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

Item #42

# messages.en.yml

oro.dashboard.title.main: "Dashboard"

oro.entity.item: "Item #%id%"

YAML:

Data Localization and Translation

Translation on frontend

require(['orotranslation/js/translator'],

function(__) {

__('oro.note.add_note_title');

__('oro.datagrid.pagination.totalRecords', {totalRecords: 42});

});

JS:

Result: Add note

Total of 42 records

# jsmessages.en.yml

oro.note.add_note_title: "Add note"

oro.datagrid.pagination:

totalRecords: "Total of {{ totalRecords }} records"

YAML:

Data Localization and Translation

Translation in the database

- table oro_translation

- entity OroTranslationBundle:Translation

- scopes SYSTEM and UI

# id

# key

# value

# locale

# domain

# scope

Translation

Data Localization and 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/Or

mTranslationLoader.php

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

tabasePersister.php

Data Localization and Translation

Translation configurationSystem > Configuration > Language settings

Data Localization and Translation

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

Data Localization and Translation

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/De

bugTranslator.php

Data Localization and Translation

Debug translator

Data Localization and Translation

Translation CLI commands

oro:translation:dump - dumps frontend

translations into web/js/translation/<locale>.js

oro:translation:pack - extracts translation files

for each bundle in specified vendor namespace

and creates language pack

Data Localization and Translation

Questions

and

Answers