TranslatorInterface.php 1.3 KB

12345678910111213141516171819202122232425262728293031323334353637
  1. <?php
  2. namespace Elgg\I18n;
  3. /**
  4. * WARNING: API IN FLUX. DO NOT USE DIRECTLY.
  5. *
  6. * Can "translate" language keys into various human-readable, localized strings.
  7. *
  8. * TODO(ewinslow): Remove the "Interface" suffix
  9. *
  10. * @since 1.11
  11. *
  12. * @access private
  13. */
  14. interface TranslatorInterface {
  15. /**
  16. * Given a message key, returns a best-effort translated string.
  17. *
  18. * If the translator doesn't know how to translate into the specified locale,
  19. * it can try translating into a related or similar locale (e.g. en-US => en).
  20. *
  21. * If no locale is specified, or if no translation can be found for the specified
  22. * locale, the translator may choose to fall back to some other language(s).
  23. *
  24. * It should never throw exceptions, since lack of translation should never be
  25. * cause to bring down an app or cancel a request. However, implementations may
  26. * log warnings to alert admins that requested language strings are missing.
  27. *
  28. * @param string $key A key identifying the message to translate.
  29. * @param array $args An array of arguments with which to format the message.
  30. * @param Locale $locale Optionally, the standard language code
  31. * (defaults to site/user default, then English)
  32. *
  33. * @return string The final, best-effort translation.
  34. */
  35. function translate($key, array $args = [], Locale $locale = null);
  36. }