When it comes to ensuring your users get the best possible user experience out of your app, it’s better to answer which countries your app will be available in sooner than later. Whether you’re building enterprise scale software or working freelance on apps for clients, internationalizing and localizing your website is no easy feat. Luckily, the community has stepped up to provide solutions to keep our code flexible and DRY. In this talk, Angular developer Sarah Hudson will answer the questions of what internationalization and localization are, and how you can setup your Angular app to handle multiple locales. We’ll go over: • The built in $locale service and filters for handling date and currency • The angular translate plugin • Handling calendars for alternative date and day of week formats • How to check for and store locale • How to force directives to refresh locale on the fly • Issues you may face while implementing i18n and questions you may want to ask

1. Internationalizing
Your Angular
App
Internationalization & Localization Basics

2. Internationalization
Basics

3. What is localization?
“Localization refers to the adaptation of a
product, application or document content to
meet the language, cultural and other
requirements of a specific target market (a
locale).”
-- W3C

4. What is localization? (cont.)
Detecting the user’s locale
Writing text in a way that the user understands based on his
locale, whether through languages, dialects, or idioms
Displaying data in a way that makes sense to the user based
on his locale
This includes: date formats, currency, time formats
Ensuring graphics and design elements communicate the
intended message
Includes colors, symbols, and icons
Also known as l10n

5. What is internationalization?
“Internationalization is the design and
development of a product, application or
document content that enables easy
localization for target audiences that vary in
culture, region, or language.”
-- W3C

6. What is internationalization? (cont.)
Building your app with the flexibility of supporting multiple
locales
Multiple languages, currencies, countries, name displays,
address displays, date and time formats
Ability to change the language, whether through browser
detection or allowing the user to choose the language of
display
Offering multiple locales to the user
Determining which character sets to use (Typically Unicode)
Also known as i18n

7. Methods of supporting i18n and l10n
1.Selecting a region and being redirected to
another page that supports that locale:
a.Subdomains for each locale that serves up different
HTML content
b.Separate websites for each locale
2.JavaScript for showing/hiding or swapping
out content

8. Detecting the browser’s locale
1. Can use the browser object:
if(navigator.language !== undefined && navigator.language !==
null){
var language = navigator.language;
language = language.toLowerCase();
} else { //Handles IE
var language = navigator.userLanguage;
language = language.toLowerCase();
};

9. Angular i18n

10. The $locale service
Angular comes with built in support for many locales. Like many of the
extra Angular services (i.e., ngRoute, ngResource, ngMocks), you’ll
have to install.
bower | npm install angular-i18n
The folder installed will contain locale files for handling the date,
currency, and number filters.
angular.module(‘myI18nApp’, [‘ngLocale’, ‘tmh.dynamicLocale’, ‘pascalprecht.translate’])

11. Built in filters for i18n
date: Takes a string parameter which translates into a format. (like:
{{dateObj.startDate | date: ‘shortDate’}}
shortDate: In en-us, formats as 09/24/2015
longDate: In en-us, formats as September 24, 2015
fullDate: In en-us, formats as Thursday, September 24, 2015
currency: Appends or prepends the currency symbol based on the current
user’s locale, as well as manages commas and decimals.
Note: Watch out! It only translates the symbol, not the monetary value.
number: When used by itself, it defaults to formatting the number to the
locale’s format. When used in conjunction with the additional parameter
fractionSize, it rounds the number to the number of places specified.
{{product.inStock | number: 3}} will display 1000 as 1,000

12. Angular
Translate

13. Angular Translate
Module that aids in i18n and l10n for
language, pluralization, and lazy loading
Can be used as a directive or filter (both in the
DOM and in the controller)
Allows you to move i18n from the server to
the client

14. Setting up Angular Translate
Plugins:
1. angular-translate: Main plugin; contains the $translate service.
2. angular-translate-loader-static-files: Helper plugin that allows
devs to specify a file name pattern for loading translation files, as
well as the preferred language to fall back on.
3. angular-translate-loader-url: Helper plugin that allows for
async/lazy loading.
4. angular-translate-partial-loader: Helper plugin that allows devs to
load the translation files for only one module.

15. Setting up Angular Translate (cont.)
Steps:
1. Download the source files
a. Download from Github
b. bower | npm install
2. Include the scripts in your page
3. Inject Angular Translate as a dependency in the module(s) you want translated
angular.module(‘myI18nApp’, [‘ngLocale’, ‘tmh.dynamicLocale’,
‘pascalprecht.translate’])
4. In your app’s configuration, if you’re using the static loader, inject the $translateProvider:
$translateProvider.useStaticFilesLoader({
prefix: '../languages/',
suffix: '.json'
});

16. Files for Translations
Should be in JSON format
Multiple files for each locale
i.e., en-gb.json for the UK, en-us for the US, es-es for Spain, es-mx for Mexico, etc etc
Each file should be stored in a common folder, i.e., ‘locale’ or ‘languages’
Can name properties with a single word, or as ‘dot notation’ to designate sections:
{
"navigation.dashboard": "Dashboard",
"navigation.appointments": "Appointments",
"navigation.addAppt": "Add New Appointment",
"navigation.addOneTimeAppt": "Add One Time Appointment",
"navigation.addRepeatingAppt": "Add Repeating Appointments",
"navigation.addTimeOff": "Add New Time Off",
....
}

17. Inserting translations in your text
Can be done several ways:
1. The translate filter
<button>{{‘btn.close’ | translate}}</button>
1. The translate directive
<button>
<span translate=“btn.close”>Close</span>
</button>
1. Using the translate filter in the controller
$translate('Home.calendar')
.then(function(translatedValue){
$scope.mainTitle = translatedValue;
})

18. Passing parameters to translated strings
1. HTML:
<div>
<span translate=“Calendar.title” translate-values=“{‘date’:
calendar.defaultDate}”>Today’s date is {{calendar.defaultDate}}</span>
</div>
2. Interpolations of the variable in JSON:
“Calendar.title”: “Today’s date is {{date}}”

19. Compiling translations with HTML
There are cases where you can’t break a line for HTML changes (links, emphasis, etc) and
keep it syntactically correct for all languages.
HTML:
<span translate= “Text.withLink” translate-compile>
To learn more, <a href=“#”>view our documentation</a>.
</span>
JSON:
“Text.withLink”: “To learn more, <a href=‘#’>view our documentation.”

20. Making Locale
Dynamic

21. Angular Dynamic Locale
Allows users to choose and change their locale
Allows developers to pass in the browser’s locale (or
stored locale) and change it from the default locale if
necessary
Changes the locale at app’s runtime, which allows you
to use a stored locale
Modifies the $locale object so changing the locale will
change all objects relying on the $locale service

22. Using Angular Dynamic Locale
1. Install with bower | npm install angular-dynamic-locale
2. Inject into your module: angular.module(‘myI18nApp’, [‘ngLocale’, ‘tmh.dynamicLocale’])
3. In your app’s configuration, do:
app.config(["tmhDynamicLocaleProvider", function(tmhDynamicLocaleProvider){
tmhDynamicLocaleProvider.localeLocationPattern(
'../bower_components/angular-i18n/angular-locale_{{locale}}.js'
);
tmhDynamicLocaleProvider.defaultLocale(language);
//Default language
if(language === 'es' || language === 'fr'){ //using this format so it won't try to pull in files that
don't exist, like es-mx
$translateProvider.use(language);
} else {
$translateProvider.preferredLanguage('en-us');
};
}]);

23. Handling Calendars -- Angular UI Bootstrap
Datepicker
Angular UI Bootstrap Datepicker: Built on top of the date filter so everything is localized.
Settings include:
starting-day
Adjustments through the controller, passed into the directive’s helper attributes
HTML:
...
<input type="text" class="form-control" datepicker-popup="shortDate" ng-model="dateObj.startDate" is-
open="datepickers.start" datepicker-options="{{dateOptions}}" date-disabled="disabled(date, mode)" close-
text="Close" ng-click="openDT($event, 'start')" />
…
JS:
var firstDayOfWeek = $window.sessionStorage.getItem(‘firstDayOfWeek’);
$scope.dateOptions = {
'starting-day': firstDayOfWeek
};

24. Handling Calendars -- Angular UI Calendar
Angular wrapper for fullCalendar. Has settings which include:
dayNames
dayNamesShort
monthNames
monthNamesShort
lang
firstDay
timeFormat
To adjust for i18n, in your HTML you need:
<div ui-calendar="uiConfig.calendar" config="uiConfig.calendar" calendar="myCalendar" class="calendar"
ng-model="eventSources"></div>
And in your controller:
var firstDayOfWeek = $window.sessionStorage.getItem(‘firstDayOfWeek’);
$scope.uiConfig = {
calendar:{
lang: currentLang,
firstDay: firstDayOfWeek,

25. Triggering
Locale Changes
on the Fly

26. Triggering locale change on directives
1. Use the $provide service and pass in the name of the directive to get the registered “map”
for that directive
a. Providers expose the directive’s API app-wide and registers them with the injectors
b. Using the decorator method, we can intercept the creation of the directive on load.
2. Catches the $delegate (the original directive’s “map”, which can then be overwritten or
monkey patched)
3. Set up listener on the directive’s scope on $localeChangeSuccess (this requires Angular
Dynamic Locale)
4. Make modifications as needed (i.e., changing the first day of the week property on a
calendar object)
5. Refresh the scope/alert the scope to the changes
a. Call a method in the directive link (i.e., scope.move() )
b. Use apply() to call the directive link with the modified scope and parameters:
originalLink.apply(this, arguments)

27. Triggering locale change on directives
$provide.decorator('daterangeDirective', function($delegate, $compile, $parse, $translate, $rootScope) {
angular.forEach($delegate, function (directive) {
var originalCompile = directive.compile;
var originalLink = directive.link;
if (originalCompile) {
directive.compile = function () {
return function ($scope, $element, $attributes, ngModel) {
$scope.$on('$localeChangeSuccess', function () {
directive.link($scope, $element, $attributes, ngModel, $compile, $parse, $translate, $rootScope); //have to run
the main fn on the directive b/c it will apply all the changes
});
originalLink.apply(this, arguments);
};
}
}
});
return $delegate;
});

28. Triggering locale change on Angular UI Calendar
$provide.decorator('uiCalendarDirective', function($delegate, $locale, $rootScope, uiCalendarConfig) {
…
directive.compile = function () {
return function (scope, elm, attrs, controller) {
scope.$on('$localeChangeSuccess', function () {
uiCalendarConfig.dayNames = $locale.DATETIME_FORMATS.DAY;
uiCalendarConfig.dayNamesShort = $locale.DATETIME_FORMATS.SHORTDAY;
uiCalendarConfig.monthNames = $locale.DATETIME_FORMATS.MONTH;
uiCalendarConfig.monthNamesShort = $locale.DATETIME_FORMATS.SHORTMONTH;
uiCalendarConfig.lang = currentLang;
});
originalLink.apply(this, arguments); //This triggers the calendar to update on language change
};
}
}
…
});

29. Storing Locale

30. Methods of Storing Locale
1. Session Storage: For temporary storage/only
detecting browser storage.
2. Local Storage: For semi-permanent storage/only
detecting browser storage.
3. Server Side: For permanent storage/when user
wants to see the app in his locale regardless of
computer/browser used to signed in.

31. Changing language
HTML: <li><a href ng-click="changeLanguage('en-us', 0, account)" class="flag flag-us"></a></li>
JS: $scope.changeLanguage = function(language, firstDayOfWeek, account){
account.locale = language;
account.firstDayOfWeek = firstDayOfWeek;
$translate.use(language);
tmhDynamicLocale.set(language);
$rootScope.$broadcast('firstDayOfWeekUpdated');
//Change language on server by updating the user account
accountData.updateAccount(accountId, account).then(function(data){
//Success ...
}, function(data){
//Error ...
})
};

32. Setting from Saved Locale
To set the app to the locale saved on the server or sessionStorage, in controller:
//Fetch data from the server/sessionStorage first
//Will default to English, thanks to the setup in app.config
if($scope.account.locale !== null){
tmhDynamicLocale.set($scope.account.locale.toLowerCase());
$translate.use($scope.account.locale.toLowerCase());
};

33. Wrapping Up

34. Food for Thought
Start implementing i18n and l10n support early in development
As you build new pages, add translations
Determine your app’s target markets/locales with business rules
Map out components and features that will need localization (I.e.,
calendars, date range pickers, timepickers, etc)
Ask yourself how automated you want l10n to be -- i.e., browser
detection, users choosing which locale, etc

35. Q&A
Questions? Comments? Fire away!

36. Resources
Links:
Angular i18n guide: https://docs.angularjs.org/guide/i18n
Angular Translate: https://angular-translate.github.io/
Angular Dynamic Locale: http://lgalfaso.github.io/angular-dynamic-locale/
W3C International: http://www.w3.org/International/
Scotch IO Tutorial: https://scotch.io/tutorials/internationalization-of-angularjs-applications
Reach out to me:
email: sarah@sarah-hudson.com
Twitter: @SarahHudson2008