Permalink
Browse files

docs(i18n): clarifies limitations of elgg.echo

`elgg.echo` is not a functional equivalent of `elgg_echo` due to core only sending
one pre-merged language file to the client.

The only useful value for the 3rd argument is the boot-time return value of
`elgg.get_language()`. No other language files are loaded, so, given any other
language, `elgg.echo` will return only the message key or possibly an English
translation.

Due to this, the RST docs no longer mention `elgg.echo`'s 3rd argument.
  • Loading branch information...
mrclay committed Apr 10, 2016
1 parent b27aee7 commit 83b2c106d5ac671ee28e28625659392de4d34b0b
Showing with 11 additions and 6 deletions.
  1. +2 −2 docs/guides/i18n.rst
  2. +9 −4 js/lib/languages.js
View
@@ -83,9 +83,9 @@ To first test whether ``elgg_echo()`` can find a translation:
Javascript API
==============
``elgg.echo(key, args, language)``
``elgg.echo(key, args)``
This function is the exact counterpart to ``elgg_echo`` in PHP.
This function is like ``elgg_echo`` in PHP.
Client-side translations are loaded asynchronously. Ensure translations are available by requiring the "elgg" AMD module:
View
@@ -34,11 +34,16 @@ elgg.get_language = function() {
/**
* Translates a string
*
* @param {String} key The string to translate
* @param {Array} argv vsprintf support
* @param {String} language The language to display it in
* @note The current system only loads a single language module per page, and it comes pre-merged with English
* translations. Hence, elgg.echo() can only return translations in the language returned by
* elgg.get_language(). Requests for other languages will fail unless a 3rd party plugin has manually
* used elgg.add_translation() to merge the language module ahead of time.
*
* @return {String} The translation
* @param {String} key Message key
* @param {Array} argv vsprintf() arguments
* @param {String} language Requested language. Not recommended (see above).
*
* @return {String} The translation or the given key if no translation available
*/
elgg.echo = function(key, argv, language) {
//elgg.echo('str', 'en')

0 comments on commit 83b2c10

Please sign in to comment.