Data localization and translation

Data Localization and Translation
Data Localization
and
Translation
Yevhen Shyshkin
yshyshkin@orocrm.com
https://github.com/yshyshkin

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 configuration
System > 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.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() }}

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 OroBundle
LocaleBundleModelFullNameInterface
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 formatting
require(['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.
/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 OroBundle
LocaleBundleModelAddressInterface
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
/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 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:

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

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 }}
/src/Oro/Bundle/LocaleBundle/Resources/public/js/formatter/datetime.js
Result: Dec 13, 2011 4:15 PM
Dec 13, 2011
2: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 formatting
require(['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
/src/Oro/Bundle/LocaleBundle/Resources/public/js/formatter/number.js

Localization CLI commands
oro: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

Recommended
translation 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:

Translation extractors
- PhpCodeExtractor - extracts formatted
strings from PHP code
- NavigationTranslationExtractor -
extracts title translations from navigation.
yml files
/src/Oro/Bundle/TranslationBundle/Extractor/PhpCodeExtractor.php
/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: Dashboard
Item #42
# messages.en.yml
oro.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 note
Total of 42 records
# jsmessages.en.yml
oro.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
/src/Oro/Bundle/TranslationBundle/Translation/OrmTranslationLoader.php
/src/Oro/Bundle/TranslationBundle/Translation/DatabasePersister.php

Translation configuration
System > 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
/src/Oro/Bundle/TranslationBundle/Translation/DebugTranslator.php

Debug translator

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

Questions
and
Answers

Data localization and translation

More Related Content

Viewers also liked

Data localization and translation