i18n.rst 2.2 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788
  1. Internationalization
  2. ####################
  3. Make your UI translatable into many different languages.
  4. If you’d like to contribute translations to Elgg, see :doc:`the contributors' guide </about/contributing>`.
  5. Overview
  6. ========
  7. Translations are stored in PHP files in the ``/languages`` directory of your plugin. Each file corresponds to a language. The format is ``/languages/{language-code}.php`` where ``{language-code}`` is the ISO 639-1 short code for the language. For example:
  8. .. code-block:: php
  9. <?php
  10. // mod/example/languages/en.php
  11. return array(
  12. ‘example:text’ => ‘Some example text’,
  13. );
  14. The default language is “en” for English.
  15. To change the wording of any phrase, provide a new mapping in your plugin’s ``{language}.php`` file for the associated key:
  16. .. code:: php
  17. <?php
  18. return array(
  19. ‘example:text’ => ‘This is an example’,
  20. );
  21. .. note::
  22. Unless you are overriding core’s or another plugin’s language strings, it is good practice for the language keys to start with your plugin name. For example: “yourplugin:success,” “yourplugin:title,” etc. This helps avoid conflicts with other language keys.
  23. Server-side API
  24. ===============
  25. ``elgg_echo($key, $args, $language)``
  26. Output the translation of the key in the current language.
  27. Example:
  28. .. code:: php
  29. echo elgg_echo(‘example:text’);
  30. It also supports variable replacement using sprintf syntax:
  31. .. code:: php
  32. // ‘welcome’ => ‘Welcome to %s, %s!’
  33. echo elgg_echo(‘welcome’, array(
  34. elgg_get_config(‘sitename’),
  35. elgg_get_logged_in_user_entity()->name,
  36. ));
  37. To force which language should be used for translation, set the third parameter:
  38. .. code:: php
  39. echo elgg_echo(‘welcome’, array(), ‘es’);
  40. Javascript API
  41. ==============
  42. ``elgg.echo(key, args, language)``
  43. This function is the exact counterpart to ``elgg_echo`` in PHP.
  44. Client-side translations are loaded asynchronously. Ensure translations are available by requiring the "elgg" AMD module:
  45. .. code-block:: javascript
  46. define(function(require) {
  47. var elgg = require("elgg");
  48. alert(elgg.echo('my_key'));
  49. });
  50. Translations are also available after the ``init, system`` JavaScript event.