Search
Contact Us

OroCRM Localization

Orocrm Localization
Denis Saltanakhmedov Avatar
Denis Saltanakhmedov

Localization or internationalization process means adapting a software to different languages, regional particularities and technical requirements of a target market. Well-designed software usually does not require code changes and deep engineering knowledges for localization or/and internationalization processes.

For example, we can use different address formats depending on a country:

Great Britain (United Kingdom, England, Scotland):
Mr. Walter C. Brown
49 Featherstone Street
LONDON
EC1Y 8SY
UNITED KINGDOM

United States of America:
John Doe
Smallsys inc
795 e Dragram
Tucson az 85705
USA

Germany:
Herrn                      
John Doe
Wittekindshof 
Schulstrasse 4
32547 Bad Oyenhausen
GERMANY

Ukraine:
John Doe
ul. Astronomicheskaya 22, kv. 33
Kharkov
12345
UKRAINE

In OroCRM every user can set up a localization for his own location. It is possible to use predefined set of localizations or create a new one.
For that go to System > Configuration > Localization:

Localization Options
OroCRM has a lot of ways for customizing locale options. Locale affects formatting of numbers, addresses, names and dates:

– Primary Location – if format address per country option is disabled, or there is no country-specific formatting, the addresses will be formatted according to the rules of primary location.

– Format Address Per Country – when this option is selected, addresses will be formatted according to the rules of their countries. Otherwise, the primary location formatting will be applied.

– First Quarter Starts On – defines the starting date of the first quarter in a year.

– Timezone – defines the timezone of your location. All dates and times will be displayed in the specified timezone.

– Currency – defines the default currency.

– Temperature Unit- defines the temperature unit. These settings will be applied for weather on the map.

– Wind Speed Unit – defines the wind speed unit. These settings will be applied for weather on the map.

Also, you can get the settings in your code, for that you need to call the service oro_locale.settings.
For example:

PHP

$localeSettings = $this->get('oro_locale.settings');
$language = $localeSettings->getLanguage();
$calendar = $localeSettings->getLanguage();
$country = $localeSettings->getCountry();
$timeZone = $localeSettings->getTimeZone();

Twig

{{ oro_locale() }}
{{ oro_currency() }}

JS

require(['orolocale/js/locale-settings’],
function(localeSettings){
localeSettings.getLanguage();
localeSettings.getCountry();
});

As you can see, OroCRM has really powerful facilities to localize your application. Below we will describe the main items of localization.

Name formating

As you may also know, different countries and regions have different conventions for formatting users names. The name formats are grouped by locale, and they can be found in name_format.yml.
For example: vendor/oro/platform/src/Oro/Bundle/LocaleBundle/Resources/config/oro/name_format.yml

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%

To format name with specific locale format use the following code:

PHP

// for en_US locale
$formatter = $container->get('oro_locale.formatter.name');
$person->setNamePrefix('Mr.');
$person->setFirstName(John);
$person->setMiddleName(J);
$person->setLastName(Doe);
$person->setNameSuffix('Sn.');
$formatter->format($person, 'en_US');

// for ru_RU locale
$formatter = $container->get('oro_locale.formatter.name');
$person->setFirstName(John);
$person->setMiddleName(J);
$person->setLastName(Doe);
$formatter->format($person, ru_RU);

Twig

Use format method from name formatter, it has similar logic:

{{ user|oro_format_name }}

JS

require(['orolocale/js/formatter/name'],
function(nameFormatter) {
   var formattedName = nameFormatter.format({
       prefix: 'Mr.',
       first_name: John,
       middle_name: J,
       last_name: Doe,
       suffix: 'Sn.'
   });
});

Address Formatting

Like in case of names, address format may depend on different conventions. Address formats are grouped by country and they can be found in address_format.yml.

Example of format configuration for US:
vendor/oro/crm/src/OroCRM/Bundle/MagentoBundle/Resources/config/oro/address_format.yml

PN:
   format: '%name%\n%organization%\n%street%\n%CITY%\n%COUNTRY%\n%POSTAL_CODE%'
   require: [street, city, postal_code]
PR:
   format: '%NAME%\n%ORGANIZATION%\n%STREET%\n%CITY% PR %postal_code%\n%COUNTRY%'
   require: [street, city, postal_code]
   zip_name_type: zip
   postprefix: PR

PHP

$formatter = $container->get('oro_locale.formatter.address');
$region->getCode();
$country->getIso2Code();
$region->setCountry($country);
$address = new Address();
$address->setStreet('16243 Ivy Lake Dr.');
$address->setCity('Odessa');
$address->setRegion($region);
$address->setPostalCode(33556);
$address->setOrganization('Atwix');
$address->setCountry($country);
$formatter->format($address);

Twig

{{ address|oro_format_address('US') }}

JS

require(['orolocale/js/formatter/address'],
function(addressFormatter) {
   var data = this.model.toJSON();
   data.formatted_address = addressFormatter.format({
       prefix: 'Mr.',
       suffix: 'Sn.',
       first_name: 'John',
       middle_name: 'J',
       last_name: 'Doe',
       organization: 'Atwix',
       street: '16243 Ivy Lake Dr.',
       city: 'Odessa',
       country: 'US',
       country_iso2: data.countryIso2,
       country_iso3: data.countryIso3,
       postal_code: '33556',
       region: data.region,
       region_code: data.regionCode
   });
});

Data and Time formating

Countries may also have different conventions for formatting data and time.
Each format uses its own localized format for date and time.
Pay attention that default date format is \IntlDateFormatter::MEDIUM, and default time format is \IntlDateFormatter::SHORT.

The “format” functions provide a basic functionality for date and time representation changes.
It allows setting up the date and time format types from Intl library: current locale as a string, current timezone as a string and custom format pattern (in this case, date and time format types will not be used).

PHP DateTime Formatter:

$formatter->format(new \DateTime('2015-12-12 09:00:00'));
// Dec 12, 2015 09:00 AM

$formatter->format(new \DateTime('2015-12-12 09:00:00'), \IntlDateFormatter::FULL, \IntlDateFormatter::MEDIUM);
// Thursday, December 12, 2015 09:00:00 AM

$formatter->format(new \DateTime('2015-12-12 09:00:00'), null, null, 'ru');
// 12.12.2015 9:00

$formatter->format(new \DateTime('2015-12-12 09:00:00'), null, null, null, 'America/Los_Angeles');
// Dec 12, 2015 9:00 AM

$formatter->format(new \DateTime('2015-12-12 09:00:00'), null, null, null, null, 'yyyy-MM-dd|HH:mm:ss');
// 2015-12-12|09:00:00

$formatter->formatDate(new \DateTime('2015-12-12 09:00:00'));
// Dec 12, 2015

$formatter->formatDate(new \DateTime('2015-12-12 09:00:00'), \IntlDateFormatter::FULL);
// Thursday, December 12, 2015

$formatter->formatDate(new \DateTime('2015-12-12 09:00:00'), null, 'ru');
// 12.12.2015

$formatter->formatDate(new \DateTime('2015-12-12 09:00:00'), null, null, 'America/Toronto');
// Dec 12, 2015

OroPlatform application has several libraries that work with DateTime values.
Each library has its own DateTime format placeholders. And note that for every library must be a format converter that contains rules of converting standard internal format to specific library format. Intl library format is used for internal format representation.

Developer can use the converter registry (DateTimeFormatConverterRegistry) that simply collects and stores the existing format converters and allows to receive appropriate converter by its alias.

LocaleBundle contains the following format converters:
– intl (IntlDateTimeFormatConverter) – default format converter that simply returns Intl formats
– moment (MomentDateTimeFormatConverter) – format converter for moment.js library

getDateFormat

It returns localized date format for specific library and optionally receives date format type form Intl library and custom locale.

$converterRegistry->getFormatConverter('intl')->getDateFormat();
// MMM d, y
$converterRegistry->getFormatConverter('moment')->getDateFormat();
// MMM D, YYYY

getTimeFormat

It returns localized time format for specific library and optionally receives time format type form Intl library and custom locale.

$converterRegistry->getFormatConverter('intl')->getTimeFormat();
//h:mm a
$converterRegistry->getFormatConverter('moment')->getTimeFormat();
//h:mm A

$converterRegistry->getFormatConverter('intl')->getTimeFormat(\IntlDateFormatter::MEDIUM, 'ru');
// H:mm:ss
$converterRegistry->getFormatConverter('moment')->getTimeFormat(\IntlDateFormatter::MEDIUM, 'ru');
// H:mm:ss

getDateTimeFormat

It returns localized datetime format for specific library and, in this case, it optionally receives date and time format types form Intl library and custom locale.

$converterRegistry->getFormatConverter('intl')->getDateTimeFormat();
// MMM d, y h:mm a
$converterRegistry->getFormatConverter('moment')->getDateTimeFormat();
// MMM D, YYYY h:mm A

$converterRegistry->getFormatConverter('intl')->getDateTimeFormat(
   \IntlDateFormatter::FULL,
   \IntlDateFormatter::MEDIUM,
   'ru'
);
// EEEE, d MMMM y 'г'. H:mm:ss
 $converterRegistry->getFormatConverter('moment')->getDateTimeFormat(
   \IntlDateFormatter::FULL,
   \IntlDateFormatter::MEDIUM,
   'ru'
);
// dddd, D MMMM YYYY [г]. H:mm:ss

Twig

LocaleBundle has two twig extensions that provide with formatter filters and format converter functions.

{{ entity.lastLogin|oro_format_date }}
{{ entity.lastLogin|oro_format_date({'locale': us}) }}
{{ entity.lastLogin|oro_format_time }}
{{ entity.lastLogin|oro_format_time({'locale': us}) }}
{{ entity.lastLogin|oro_format_datetime }}
{{ entity.lastLogin|oro_format_datetime({'locale': us}) }}

JS

From the frontend side, there is JavaScript datetime converter that provides functions to format datetime values. Formatter uses library moment.js to work with datetime values, so localized formats injected from locale settings configuration.

datetimeFormatter.getDateTimeFormat();
// MMM D, YYYY h:mm A

datetimeFormatter.isDateValid('qwerty');
// false

datetimeFormatter.isDateTimeValid('dec 12 2015 09:00 am');
// true

datetimeFormatter.formatDate('2015-12-12');
// Dec 12, 2015

datetimeFormatter.formatDateTime(new Date());
// Dec, 2015 09:00 AM

datetimeFormatter.convertDateToBackendFormat('Dec 12, 2015');
// 2015-12-12

datetimeFormatter.convertDateTimeToBackendFormat(Des 12, 2015 9:00 AM');
// 2015-12-012T09:00:00+0200

Number formatting

Numbers can have a lot of types and formats, we may use default PHP or JS format methods or use methods provided by OroCRM.

We use specific class “numberformatter” for numbers formatting:
Oro\Bundle\LocaleBundle\Formatter\NumberFormatter (service: oro_locale.formatter.number)
This class formats different styles of numbers in localized format and proxies Intl extension class. Methods of NumberFormatter can receive values of original Intl NumberFormatter constants.
Moreover, each constant can be passed to an appropriate method of NumberFormatter as a string name.
For example, few methods of NumberFormatter class:

$numberFormatter->format(1234.56789, \NumberFormatter::DECIMAL);
// outputs: "1,234.568" if default locale is en_US

$numberFormatter->formatCurrency(1234.56789);
// outputs: "$1,234.57" if default locale is en_US and currency is 'USD'

$numberFormatter->formatDecimal(1234.56789);
// outputs: "1,234.568" if default locale is en_US and currency is 'USD'

$numberFormatter->formatPercent(1);
// outputs: "100%"

$numberFormatter->formatSpellout(1);
// outputs: "one"

$numberFormatter->formatOrdinal(1);
// outputs: "1st"

Twig

Also, you can use twig methods for formatting numbers:

{{ 10000|oro_format_number('decimal') }}
{{ 1234.56789|oro_format_decimal }}
{{ 100000|oro_format_currency }}
{{ 1|oro_format_percent }}

JS

On JS side, the number formatter is available via module “orolocale/js/formatter/number”. This module provides with the following functions for different cases:

//Formats number to decimal localized format.
require(['orolocale/js/formatter/number'], function(numberFormatter) {
     numberFormatter.formatDecimal(10000);
   // 10,000.000 
});

//Formats number to integer localized format.
require(['orolocale/js/formatter/number'], function(numberFormatter) {
    numberFormatter.formatInteger(10000);
 // 10,000
});

//Formats number to percent localized format.
require(['orolocale/js/formatter/number'], function(numberFormatter) {
  numberFormatter.formatPercent(.5);
 // 50% 
});

//Formats number to currency localized format. If currency is not specified, then default one will be used.
require(['orolocale/js/formatter/number'], function(numberFormatter) {
    numberFormatter.formatCurrency(-50000.45);
 // $50,000.45
});

//Parses a number from localized number string. Can be used to parse all styles of localized numbers.

require(['orolocale/js/formatter/number'], function(numberFormatter) {
     numberFormatter.unformat('$50,000.45');
   // 50000.45
   
  numberFormatter.unformat('95%');
   // 0.95

     numberFormatter.unformat('(1,000,000.456)');
// -1000000.456

  numberFormatter.unformat(atwix);
// NaN
});

In this article we’ve described the general concepts of OroCRM localization. Meanwhile, you can find more information in OroCRM documentation. As you can see, using localization you can create convenient application for your users and we hope you will find our tips helpful.

Share post: