PageRenderTime 42ms CodeModel.GetById 16ms RepoModel.GetById 0ms app.codeStats 0ms

/src/phpDocumentor/Translator/Translator.php

https://github.com/yuta13bt/phpDocumentor2
PHP | 195 lines | 51 code | 19 blank | 125 comment | 3 complexity | 089ef9bdd1594d96378091fb0cf384ca MD5 | raw file
  1. <?php
  2. /**
  3. * phpDocumentor
  4. *
  5. * PHP Version 5.3
  6. *
  7. * @copyright 2010-2014 Mike van Riel / Naenius (http://www.naenius.com)
  8. * @license http://www.opensource.org/licenses/mit-license.php MIT
  9. * @link http://phpdoc.org
  10. */
  11. namespace phpDocumentor\Translator;
  12. use Zend\I18n\Translator\Translator as ZendTranslator;
  13. /**
  14. * Translator proxy for phpDocumentor.
  15. *
  16. * This class encapsulates (or actually extends) a Translator object that can be used to translate messages from the
  17. * fallback language to another.
  18. *
  19. * This encapsulation serves two purposes;
  20. *
  21. * 1. To make a migration to another translator easier if necessary
  22. * 2. To fix a bug in Zend\I18n\Translator\Translator where the cache is not cleared when new messages are added.
  23. *
  24. * Due to issue 2 this class extends the Zend Translator and does not use composition to proxy calls to the translator;
  25. * as such it is not recommended to use any public function not defined in this proxy as it may be removed.
  26. *
  27. * Before invoking the {@see self::translate()} method the user must first load a series of translation messages in the
  28. * desired locale; this can be done by invoking the {@see self::addTranslationFile()} or
  29. * {@see self::addTranslationFolder()} methods. These try to include a file containing a plain PHP Array and merge that
  30. * with the translation table of this translator.
  31. *
  32. * An example of a translation file can be:
  33. *
  34. * ```
  35. * return array(
  36. * 'KEY' => 'translated message',
  37. * );
  38. * ```
  39. */
  40. class Translator extends ZendTranslator
  41. {
  42. /**
  43. * The translation file type.
  44. *
  45. * This type is hardcoded into a constant to simplify the signature of the addTranslationFile and
  46. * addTranslationFilePattern methods. This will simplify the migration to another component in the future as an
  47. * incompatibility between two libraries may emerge due to differing types or typenames.
  48. *
  49. * This translator class may be used by plugin developers to have translating elements in their plugins; as such
  50. * the signatures here are considered to be stable / api.
  51. * @var string
  52. */
  53. const TRANSLATION_FILE_TYPE = 'phparray';
  54. /** @var string Represents the default locale for phpDocumentor */
  55. const DEFAULT_LOCALE = 'en';
  56. /** @var string Translation strings may be divided into 'domains', this is the default domain */
  57. const DEFAULT_DOMAIN = 'default';
  58. /** @var string the default name of files loaded by {@see self::addTranslationFolder()} */
  59. const DEFAULT_PATTERN = '%s.php';
  60. /**
  61. * Pre-set the translator with the default locale as fallback.
  62. */
  63. public function __construct()
  64. {
  65. $this->setLocale(self::DEFAULT_LOCALE);
  66. $this->setFallbackLocale(self::DEFAULT_LOCALE);
  67. }
  68. /**
  69. * Sets the default locale to use when translating messages.
  70. *
  71. * @param string $locale
  72. *
  73. * @api
  74. *
  75. * @return Translator
  76. */
  77. public function setLocale($locale)
  78. {
  79. return parent::setLocale($locale);
  80. }
  81. /**
  82. * Adds a translation file for a specific locale, or the default locale when none is provided.
  83. *
  84. * @param string $filename Name of the file to add.
  85. * @param string|null $locale The locale to assign to, matches
  86. * {@link http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO-639-1} and defaults to en (English).
  87. * @param string $textDomain Translations may be divided into separate files / domains; this represents in
  88. * which domain the translation should be.
  89. *
  90. * @api
  91. *
  92. * @return $this
  93. */
  94. public function addTranslations($filename, $locale = self::DEFAULT_LOCALE, $textDomain = self::DEFAULT_DOMAIN)
  95. {
  96. parent::addTranslationFile(self::TRANSLATION_FILE_TYPE, $filename, $textDomain, $locale);
  97. $this->messages = array();
  98. return $this;
  99. }
  100. /**
  101. * Adds a folder with files containing translation sources.
  102. *
  103. * This method scans the provided folder for any file matching the following format:
  104. *
  105. * `[domain].[locale].php`
  106. *
  107. * If the domain matches the {@see self::DEFAULT_DOMAIN default domain} then that part is omitted and the filename
  108. * should match:
  109. *
  110. * `[locale].php`
  111. *
  112. * @link http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for a list of ISO-639-1 locale codes as used by
  113. * this method.
  114. *
  115. * @param string $folder Name of the folder, it is recommended to use an absolute path.
  116. * @param string[] $domains One or more domains to load, when none is provided only the default is added.
  117. *
  118. * @api
  119. *
  120. * @return $this
  121. */
  122. public function addTranslationFolder($folder, array $domains = array())
  123. {
  124. if (empty($domains)) {
  125. $domains = array(self::DEFAULT_DOMAIN);
  126. }
  127. foreach ($domains as $domain) {
  128. $this->addTranslationsUsingPattern($folder, $domain);
  129. }
  130. return $this;
  131. }
  132. /**
  133. * Adds a series of translation files given a pattern.
  134. *
  135. * This method will search the base directory for a series of files matching the given pattern (where %s is replaces
  136. * by the two-letter locale shorthand) and adds any translations to the translation table.
  137. *
  138. * @param string $baseDir Directory to search in (not-recursive)
  139. * @param string $textDomain The domain to assign the translation messages to.
  140. * @param string $pattern The pattern used to load files for all languages, one variable `%s` is supported and
  141. * is replaced with the {@link http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO-639-1 code} for each
  142. * locale that is requested by the translate method.
  143. *
  144. * @internal this method is not to be used by consumers; it is an extension of the Zend Translator component
  145. * and is overridden to clear the messages caching array so it may be rebuild.
  146. *
  147. * @see self::addTranslationFolder() to provide a series of translation files.
  148. *
  149. * @return $this|ZendTranslator
  150. */
  151. public function addTranslationsUsingPattern(
  152. $baseDir,
  153. $textDomain = self::DEFAULT_DOMAIN,
  154. $pattern = self::DEFAULT_PATTERN
  155. ) {
  156. if ($textDomain !== self::DEFAULT_DOMAIN && $pattern === self::DEFAULT_PATTERN) {
  157. $pattern = $textDomain . '.' . $pattern;
  158. }
  159. parent::addTranslationFilePattern(self::TRANSLATION_FILE_TYPE, $baseDir, $pattern, $textDomain);
  160. $this->messages = array();
  161. return $this;
  162. }
  163. /**
  164. * Attempts to translate the given message or code into the provided locale.
  165. *
  166. * @param string $message The message or code to translate.
  167. * @param string $textDomain A message may be located in a domain, here you can provide in which.
  168. * @param null $locale The locale to translate to or the default if not set.
  169. *
  170. * @return string
  171. */
  172. public function translate($message, $textDomain = self::DEFAULT_DOMAIN, $locale = null)
  173. {
  174. return parent::translate($message, $textDomain, $locale);
  175. }
  176. }