Awesome
I18n-harmony
I18n library that's using ES2015 template string syntax (but with reduced functionality).
Minified: ~1.6KB (~870B gziped)
Also supports:
- Global variables (either per locale or for all of them)
- Translation postProcessor
How to install
- Bower:
bower install i18n-harmony
- npm:
npm install i18n-harmony
Dependencies: None
Works as a AMD (Require.js) module, CommonJS (node.js) module or as a global library.
Features
Global & local (per locale) variables
- Variables you don't need to define every time you use a translation
- Priority: inline, local, global.
Nested translations
- If you want more than key-value, you can nest them and use
nestingSeparator
to separate the keys - Example:
I18n.t('profile.name')
Plural support
- When you pass
count
to thet
function, it will check if the string should be in plural - By default, singular will be when count is 1, and plural otherwise
- By default, the key will get the suffix
_one
or_other
- The behaviour can be tweaked using the
suffixSeparator
orsuffixFunction
Fallbacks
- Default locale: In case you don't have all phrases translated, you can fall back to the default locale (
default
) - Missing locale: In case the key is not found, the key will be returned, but it can be prefixed with the locale in order to simplify debugging (
markMissing
) - Missing variable: If a variable is not defined, the placeholder can be either removed or it can stay in the final translation (
keepPlaceholder
) - If needed, you can use the
has
method if a certain translation exists
Post processing
- Sometimes, there is a need to do some post processing before the translation is ready
- Default behaviour is to replace all occurances of
"\n"
with"<br />"
, but it can be overriden with thepostProcessor
option
Documentation
Methods
init(options)
Initializes the library. Options:
- translations
- Object with locales as keys and maps of translations as values
- globals
- keys are locale names or "all"
- values are maps of global variables
- markMissing (default:
true
)- if a translation is missing, it will add
locale:
in front of the key when it's returned by thet
function
- if a translation is missing, it will add
- preProcessor
- function that will execute before the translation key is used to find the translation when
t
andhas
functions are executed - receives the same three arguments as the
t
function - useful in cases where the translation keys have changed, but the code is still using old keys (e.g. during refactoring)
- function that will execute before the translation key is used to find the translation when
- postProcessor
- function that will be executed just before the
t
function returns the result - receives three argument - the interpolated string, translation key and received arguments
- default function will replace newlines with line breaks
- function that will be executed just before the
- findTranslation
- Default function will try to get the key directly and if it doesn't succeed, it will split the key with
nestingSeparator
and try to find the nested value - Function receives the key and object with translations and should return the translation that should be used
- Default function will try to get the key directly and if it doesn't succeed, it will split the key with
- nestingSeparator (default:
"."
)- The separator used for nesting
- Not relevant if
findTranslation
function is defined
- suffixFunction
- function that decides which suffix should be used based on the count argument
- gets four arguments: count, key, options (passed to the
t
function) and current locale (either active or default) - it should return a suffix that will be appended to the key
- default function returns
"_one"
if count is 1, and"_other"
in all other cases
- suffixSeparator (default:
"_"
)- Separator used for suffix
- In order to use nesting, set this value to the same value as
nestingSeparator
- Not relevant if
suffixFunction
function is defined
- active
- active locale
- default (default:
null
)- default locale that will be used as fallback if the phrase doesn't exist in the active locale
- keepPlaceholder (default:
false
)- keep the placeholder if the variable isn't defined
add(key, translation, [locale=activeLocale])
Add a translation to the locale
add(translations, [locale=activeLocale])
Add multiple translations to the locale. The first argument is a map of all the translations that should be added.
t(key, [options], [locale=activeLocale])
Get the interpolated string. Options is an object with local variables, and count parameter
has(key, [options], [includeDefault=false], [locale=activeLocale])
Check if the translation key exists in the active locale (if includeDefault is set as true, it will also check the default locale)
Properties
locale
Get or set the active locale
globals (read-only)
Get the globals object - object can be edited, but not replaced.
Changelog
1.6
- New option:
preProcessor
1.5
- Nested keys (Usage example)
- New option:
findTranslation
- New option:
nestingSeparator
- New option:
suffixSeparator
1.4
- Added optional
locale
parameter to thet
andhas
functions
1.3
- Added key and args parameters to the postProcessor function
has
function to check if a translation key exists
1.2
- Default locale
- Suffix function
1.1
- Minified version
- Readme fixes
1.0
- Initial release