Hi all!
I'm pleased to introduce new API library in our arsenal - mozIntl. mozIntl is
going to be a staging area for future Intl API functionality so that we can
centralize the code and make sure that the future Ecma API will match our needs.
With that, we close our current Intl related API functionality with - Intl API,
mozIntl API and IntlHelper and deprecated shared/js/l10n_date.js.
This is a huge milestone and it brings us:
- more localizable user interfaces
- better RTL coverage
- lower burden on our localizers
- improved performance
- improved memory management
- faster startup times
- less race conditions
- cleaner codebase
I know, it's huge. I'm excited. :)
So, without further due, let me introduce the stars of the show and if you
write *any* user interface code for Gaia, you should get cozy with them:
1) Intl API
The one, the only, the backbone of our Intl story - Javascript Intl API.
It should be used everywhere where you throw Date, Time, Numbers at the screen,
or where you sort or search text.
Example usage:
date.toLocaleString(navigator.languages, {
hour12: navigator.mozHour12,
hour: 'numeric',
minute: 'numeric'
});
value.toLocaleString(navigator.languages, {
style: 'decimal',
useGrouping: false,
minimumIntegerDigits: 2
});
The patterns we use are:
- `navigator.languages` for locales
- `navigator.mozHour12` for hour12[0]
One thing to notice is that toLocaleString is not very fast, so if your code is
in the loop or you need performance (d'uh!), you should use DateTime|Number
Formatters and cache them.
When you cache them, you will need to react to `timeformatchange` and
`langaugechange` to recreate the formatter and reformat the values.
To aid you with that, comes:
2) IntlHelper - shared/js/intl_helper.js
IntlHelper is a singleton per app that caches and managers Intl formatters and
helps you with reformatting triggers. Example:
====================
IntlHelper.define('digit-padding', 'number', {
style: 'decimal',
useGrouping: false,
minimumIntegerDigits: 2
});
IntlHelper.define('shorttime', 'datetime', {
hour: 'numeric',
minute: 'numeric'
});
function setIntlValues() {
var numFormatter = IntlHelper.get('digit-padding');
var value = minElem.getAttribute('data-value');
minElem.setAttribute('data-l10n-args', JSON.stringify({minutes:
numFormatter.format(value)}));
var timeFormatter = IntlHelper.get('shorttime');
timeElem.textContent = timeFormatter.format(alarm.startTime);
}
IntlHelper.observe(['shorttime', 'digit-padding'], setIntlValues);
====================
IntlHelper will set hour12 for you, and inform you intelligently when
timeformat changes only if your formatter requires it.
3) mozIntl - shared/js/moz_intl.js
MozIntl is the most exciting one. As we're working on the next revision of Intl
API, we want to make sure that it matches our experience and needs with Firefox
OS, so we set up this staging area where future APIs are going to be shimmed.
This will allow us to make sure that what we standardizes matches our needs and
also make it simpler for your code to be moved from the shim to Intl API once
its ready.
Initially there are five things in mozIntl:
a) mozIntl.formatList
Allows you to format lists according to locale. For example "John, Mary, Nick".
In the future we will allow for more "humane" formatting like "John, Mary and
Nick".
b) mozIntl.DateTimeFormat
it extends Intl.DateTimeFormat with two new features:
- dayperiod token removal:
mozIntl.DateTimeFormat(navigator.languages, {
hour12: navigator.mozHour12,
hour: 'numeric',
minute: 'numeric',
dayperiod: false
});
will proceed time without day period token. Needed for Lockscreen, System
status bar time etc. Not recommended for most code.
- token formatting:
var formatter = mozIntl.DateTimeFormat(navigator.languages, {
hour12: navigator.mozHour12,
hour: 'numeric',
minute: 'numeric',
});
formatter.format(date, {
dayperiod: "<small>$&</small>"
});
will produce "10:12 <small>am</small>".
Other uses: "Saturday, July <strong>23</strong>", etc.
c) mozIntl.calendarInfo
provides you the `firstDayOfTheWeek` token. In the future we will add more,
like `weekendStarts` and `weekendEnds` and other calendaring information for
the given locale.
d) mozIntl.DurationFormat
this formatter allows you to format integer with milliseconds into a duration
format (like the one Timer uses) - 'hh:mm:ss' or 'mm:ss.SS'.
e) mozIntl.RelativeTimeFormat
This allows for building relative time formattings like "5 minutes ago", "in 5
minutes" etc.
========================================================
All of those new features are working with each other (for example mozIntl's
DurationFormat and DateTimeFormat can be registered in IntlHelper as type
'mozduration' and 'mozdatetime').
If your code still uses old shared/js/l10n_date.js, please upgrade your code or
help me by reviewing the patch once I send it your way. I want to remove it in
2.5 to lower the burden on our localizers.
Questions? Feedback? :gandalf and :stas will be happy to help!
Greetings,
zb.
[0] You will need shared/js/date_time_helper.js until we move it to platform
_______________________________________________
dev-fxos mailing list
[email protected]
https://lists.mozilla.org/listinfo/dev-fxos
