i18n()
Internationalisation token lookup.
Description
This method is designed for use by plug-in and extension developers building upon DataTables, where the software will present language strings to end users. It provides the ability to use the language configuration object as a single point of configuration for language strings and then look up values from that object. Defaults should be provided for cases where the developer has not provided their own string.
The i18n() method also provides basic support for singular, plural, dual, etc forms that must be taken into account when considering internationalisation. This is done by providing an object that contains the keys of the form to be used, as well as a default.
Consider for example the following object:
{
_: "%d rows selected",
0: "Click a row to select",
1: "1 row selected"
}
In the case where 0 is passed in as the numeric value (third parameter) the "Click a row to select" string will be used. For 1, the "1 row selected" string will be used. For all other values the default _ parameter's value will be used with the %d replaced by the numeric value. For languages that use a dual form add a 2 parameter, etc.
It should be noted that internationalisation (i18n for short) / localisation (l10n for short) is hard. This method provides good support for basic internationalisation in DataTables and its components, but not complete support. Complete support is outside the scope of the DataTables library at this time and is a full project itself!
Type
function i18n( token, def [, numeric ] )
- Description:
Look up a language token that was defined in the DataTables'
languageinitialisation object.- Parameters:
Name Type Optional 1 tokenNo The language token to lookup from the language object. The token should be given in Javascript dotted object notation (as a string) which will be used by DataTables to lookup the resulting value. This value follows the same rules as
columns.dataas a string.2 defNo The default value to use if the DataTables initialisation has not specified a value. This can be a string for simple cases, or an object for plurals.
In the case of plurals, a parameter named
_must be defined - this is the default. For numbers where you wish to have special strings (for example a singular form in English or a dual in Arabic) the number should be defined as the parameter name. If there is no parameter defined for the number requested, the default will be used.The characters
%dwill be replaced in the string by the value given for thenumericparameter passed to this function.3 numericYes If handling numeric output, the number to be presented should be given in this parameter. If not numeric operator is required (for example button label text) this parameter is not required.
- Returns:
Resulting internationalised string
Examples
Simple string lookup with no use defined string (i.e. use default):
var table = new DataTable('#myTable');
// Will show "Copy to clipboard"
alert(table.i18n('buttons.copy', 'Copy to clipboard'));As above, but with a developer defined value:
var table = $('#myTable').DataTable({
language: {
buttons: {
copy: 'Click to copy'
}
}
});
// Will show "Click to copy"
alert(table.i18n('buttons.copy', 'Copy to clipboard'));Plural form with no developer defined options:
var table = new DataTable('#myTable');
// Will show "0 rows selected"
alert(
table.i18n(
'select.rows',
{
_: '%d rows selected',
1: '1 row selected'
},
0
)
);
// Will show "1 row selected"
alert(
table.i18n(
'select.rows',
{
_: '%d rows selected',
1: '1 row selected'
},
1
)
);
// Will show "4 rows selected"
alert(
table.i18n(
'select.rows',
{
_: '%d rows selected',
1: '1 row selected'
},
4
)
);Plural form with developer defined options:
var table = $('#myTable').DataTable({
language: {
select: {
rows: {
_: '%d rows selected',
0: 'Click a row to select',
1: 'Just one row selected'
}
}
}
});
// Will show "Click a row to select"
alert(
table.i18n(
'select.rows',
{
_: '%d rows selected',
1: '1 row selected'
},
0
)
);
// Will show "Just one row selected"
alert(
table.i18n(
'select.rows',
{
_: '%d rows selected',
1: '1 row selected'
},
1
)
);
// Will show "4 rows selected"
alert(
table.i18n(
'select.rows',
{
_: '%d rows selected',
1: '1 row selected'
},
4
)
);Related
The following options are directly related and may also be useful in your application development.