---
layout: doc
title: delite/nls
---

# Internationalization and localization in delite

## Locale

Delite supports a locale setting for the page.
This affects the language of boilerplate text in widgets as well as localizations
such as how numbers and dates are displayed.
The setting is based on the browser's locale, and affects all widgets on the page.

Note that the HTML `lang` attribute set on individual elements is ignored.
This is because widgets load messages via the `i18n!` plugin, which uses the locale of the page.

## RTL and BIDI support

Delite and dependent projects like deliteful can render widgets in either LTR or RTL.
Support for RTL encompasses features like:

* GUI layout (ex: whether a Combobox's arrow is to the left or right of the `<input>` area)
* Keyboard control: make sure that the left and right arrow keys move to the left and right (respectively) even when
the page is in RTL mode.

### Limitations of RTL support

For reasons of performance and practicality, delite has certain restrictions on its RTL and bidi support.

Delite's API is currently optimized to support the following cases:

1. application GUI layout and user data is LTR text
2. application GUI layout and user data is RTL text

In either case, delite will do the right thing simply by setting `<html dir=ltr>` or `<html dir=rtl>`.

Delite also has limited support for displaying part of the page in RTL but other parts in LTR,
by directly setting the `dir` property of individual widgets.

In any case, the application should obey the following rules:

* Applications should not set `dir=ltr` or `dir=rtl` except on `<html>` and on individual widgets.
* Applications should not set `dir=auto` on any widget, nor on any ancestor node.
* Applications should not change the `dir` setting on `<html>` after widgets have been instantiated.
* If the application changes the `dir` property of any widget or node,
then it must explicitly set `dir` on all descendant widgets too.

Breaking any of these rules will lead to undefined behavior.  Often it will lead to widgets being in a half-way
state where, for example, the layout becomes RTL but the keyboard support is still in LTR mode.

## Writing widgets

Ibm-js provides two modules that can be used to build widgets with internationalization support:

* [`requirejs-dplugins/i18n`](/requirejs-dplugins/docs/0.5.0/i18n.html) - A plugin to load
localized text (error messages, etc.) based on the browser's locale.
* [`ecma402`](https://github.com/ibm-js/ecma402/blob/master/README.md) - An implementation of the
[ECMA-402 JavaScript Internationalization APIs standard](http://www.ecma-international.org/ecma-402/1.0/ECMA-402.pdf)
for number formatting ( Intl.NumberFormat ) and date and time formatting ( Intl.DateTimeFormat ).

Please see those respective pages for details.