field.multilingual.inc 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301
  1. <?php
  2. /**
  3. * @file
  4. * Functions implementing Field API multilingual support.
  5. */
  6. /**
  7. * @defgroup field_language Field Language API
  8. * @{
  9. * Handling of multilingual fields.
  10. *
  11. * Fields natively implement multilingual support, and all fields use the
  12. * following structure:
  13. * @code
  14. * $entity->{$field_name}[$langcode][$delta][$column_name]
  15. * @endcode
  16. * Every field can hold a single or multiple value for each language belonging
  17. * to the available languages set:
  18. * - For untranslatable fields this set only contains LANGUAGE_NONE.
  19. * - For translatable fields this set can contain any language code. By default
  20. * it is the list returned by field_content_languages(), which contains all
  21. * installed languages with the addition of LANGUAGE_NONE. This default can be
  22. * altered by modules implementing hook_field_available_languages_alter().
  23. *
  24. * The available languages for a particular field are returned by
  25. * field_available_languages(). Whether a field is translatable is determined by
  26. * calling field_is_translatable(), which checks the $field['translatable']
  27. * property returned by field_info_field(), and whether there is at least one
  28. * translation handler available for the field. A translation handler is a
  29. * module registering itself via hook_entity_info() to handle field
  30. * translations.
  31. *
  32. * By default, _field_invoke() and _field_invoke_multiple() are processing a
  33. * field in all available languages, unless they are given a language
  34. * suggestion. Based on that suggestion, _field_language_suggestion() determines
  35. * the languages to act on.
  36. *
  37. * Most field_attach_*() functions act on all available languages, except for
  38. * the following:
  39. * - field_attach_form() only takes a single language code, specifying which
  40. * language the field values will be submitted in.
  41. * - field_attach_view() requires the language the entity will be displayed in.
  42. * Since it is unknown whether a field translation exists for the requested
  43. * language, the translation handler is responsible for performing one of the
  44. * following actions:
  45. * - Ignore missing translations, i.e. do not show any field values for the
  46. * requested language. For example, see locale_field_language_alter().
  47. * - Provide a value in a different language as fallback. By default, the
  48. * fallback logic is applied separately to each field to ensure that there
  49. * is a value for each field to display.
  50. * The field language fallback logic relies on the global language fallback
  51. * configuration. Therefore, the displayed field values can be in the
  52. * requested language, but may be different if no values for the requested
  53. * language are available. The default language fallback rules inspect all the
  54. * enabled languages ordered by their weight. This behavior can be altered or
  55. * even disabled by modules implementing hook_field_language_alter(), making
  56. * it possible to choose the first approach. The display language for each
  57. * field is returned by field_language().
  58. *
  59. * See @link field Field API @endlink for information about the other parts of
  60. * the Field API.
  61. */
  62. /**
  63. * Implements hook_multilingual_settings_changed().
  64. */
  65. function field_multilingual_settings_changed() {
  66. field_info_cache_clear();
  67. }
  68. /**
  69. * Collects the available languages for the given entity type and field.
  70. *
  71. * If the given field has language support enabled, an array of available
  72. * languages will be returned, otherwise only LANGUAGE_NONE will be returned.
  73. * Since the default value for a 'translatable' entity property is FALSE, we
  74. * ensure that only entities that are able to handle translations actually get
  75. * translatable fields.
  76. *
  77. * @param $entity_type
  78. * The type of the entity the field is attached to, e.g. 'node' or 'user'.
  79. * @param $field
  80. * A field structure.
  81. *
  82. * @return
  83. * An array of valid language codes.
  84. */
  85. function field_available_languages($entity_type, $field) {
  86. static $drupal_static_fast;
  87. if (!isset($drupal_static_fast)) {
  88. $drupal_static_fast['field_languages'] = &drupal_static(__FUNCTION__);
  89. }
  90. $field_languages = &$drupal_static_fast['field_languages'];
  91. $field_name = $field['field_name'];
  92. if (!isset($field_languages[$entity_type][$field_name])) {
  93. // If the field has language support enabled we retrieve an (alterable) list
  94. // of enabled languages, otherwise we return just LANGUAGE_NONE.
  95. if (field_is_translatable($entity_type, $field)) {
  96. $languages = field_content_languages();
  97. // Let other modules alter the available languages.
  98. $context = array('entity_type' => $entity_type, 'field' => $field);
  99. drupal_alter('field_available_languages', $languages, $context);
  100. $field_languages[$entity_type][$field_name] = $languages;
  101. }
  102. else {
  103. $field_languages[$entity_type][$field_name] = array(LANGUAGE_NONE);
  104. }
  105. }
  106. return $field_languages[$entity_type][$field_name];
  107. }
  108. /**
  109. * Process the given language suggestion based on the available languages.
  110. *
  111. * If a non-empty language suggestion is provided it must appear among the
  112. * available languages, otherwise it will be ignored.
  113. *
  114. * @param $available_languages
  115. * An array of valid language codes.
  116. * @param $language_suggestion
  117. * A language code or an array of language codes keyed by field name.
  118. * @param $field_name
  119. * The name of the field being processed.
  120. *
  121. * @return
  122. * An array of valid language codes.
  123. */
  124. function _field_language_suggestion($available_languages, $language_suggestion, $field_name) {
  125. // Handle possible language suggestions.
  126. if (!empty($language_suggestion)) {
  127. // We might have an array of language suggestions keyed by field name.
  128. if (is_array($language_suggestion) && isset($language_suggestion[$field_name])) {
  129. $language_suggestion = $language_suggestion[$field_name];
  130. }
  131. // If we have a language suggestion and the suggested language is available,
  132. // we return only it.
  133. if (in_array($language_suggestion, $available_languages)) {
  134. $available_languages = array($language_suggestion);
  135. }
  136. }
  137. return $available_languages;
  138. }
  139. /**
  140. * Returns available content languages.
  141. *
  142. * The languages that may be associated to fields include LANGUAGE_NONE.
  143. *
  144. * @return
  145. * An array of language codes.
  146. */
  147. function field_content_languages() {
  148. return array_keys(language_list() + array(LANGUAGE_NONE => NULL));
  149. }
  150. /**
  151. * Checks whether a field has language support.
  152. *
  153. * A field has language support enabled if its 'translatable' property is set to
  154. * TRUE, and its entity type has at least one translation handler registered.
  155. *
  156. * @param $entity_type
  157. * The type of the entity the field is attached to.
  158. * @param $field
  159. * A field data structure.
  160. *
  161. * @return
  162. * TRUE if the field can be translated.
  163. */
  164. function field_is_translatable($entity_type, $field) {
  165. return $field['translatable'] && field_has_translation_handler($entity_type);
  166. }
  167. /**
  168. * Checks if a module is registered as a translation handler for a given entity.
  169. *
  170. * If no handler is passed, simply check if there is any translation handler
  171. * enabled for the given entity type.
  172. *
  173. * @param $entity_type
  174. * The type of the entity whose fields are to be translated.
  175. * @param $handler
  176. * (optional) The name of the handler to be checked. Defaults to NULL.
  177. *
  178. * @return
  179. * TRUE, if the given handler is allowed to manage field translations. If no
  180. * handler is passed, TRUE means there is at least one registered translation
  181. * handler.
  182. */
  183. function field_has_translation_handler($entity_type, $handler = NULL) {
  184. $entity_info = entity_get_info($entity_type);
  185. if (isset($handler)) {
  186. return !empty($entity_info['translation'][$handler]);
  187. }
  188. elseif (isset($entity_info['translation'])) {
  189. foreach ($entity_info['translation'] as $handler_info) {
  190. // The translation handler must use a non-empty data structure.
  191. if (!empty($handler_info)) {
  192. return TRUE;
  193. }
  194. }
  195. }
  196. return FALSE;
  197. }
  198. /**
  199. * Ensures that a given language code is valid.
  200. *
  201. * Checks whether the given language is one of the enabled languages. Otherwise,
  202. * it returns the current, global language; or the site's default language, if
  203. * the additional parameter $default is TRUE.
  204. *
  205. * @param $langcode
  206. * The language code to validate.
  207. * @param $default
  208. * Whether to return the default language code or the current language code in
  209. * case $langcode is invalid.
  210. * @return
  211. * A valid language code.
  212. */
  213. function field_valid_language($langcode, $default = TRUE) {
  214. $enabled_languages = field_content_languages();
  215. if (in_array($langcode, $enabled_languages)) {
  216. return $langcode;
  217. }
  218. global $language_content;
  219. return $default ? language_default('language') : $language_content->language;
  220. }
  221. /**
  222. * Returns the display language for the fields attached to the given entity.
  223. *
  224. * The actual language for each given field is determined based on the requested
  225. * language and the actual data available in the fields themselves.
  226. * If there is no registered translation handler for the given entity type, the
  227. * display language to be used is just LANGUAGE_NONE, as no other language code
  228. * is allowed by field_available_languages().
  229. * If translation handlers are found, we let modules provide alternative display
  230. * languages for fields not having the requested language available.
  231. * Core language fallback rules are provided by locale_field_language_fallback()
  232. * which is called by locale_field_language_alter().
  233. *
  234. * @param $entity_type
  235. * The type of $entity.
  236. * @param $entity
  237. * The entity to be displayed.
  238. * @param $field_name
  239. * (optional) The name of the field to be displayed. Defaults to NULL. If
  240. * no value is specified, the display languages for every field attached to
  241. * the given entity will be returned.
  242. * @param $langcode
  243. * (optional) The language code $entity has to be displayed in. Defaults to
  244. * NULL. If no value is given the current language will be used.
  245. *
  246. * @return
  247. * A language code if a field name is specified, an array of language codes
  248. * keyed by field name otherwise.
  249. */
  250. function field_language($entity_type, $entity, $field_name = NULL, $langcode = NULL) {
  251. $display_languages = &drupal_static(__FUNCTION__, array());
  252. list($id, , $bundle) = entity_extract_ids($entity_type, $entity);
  253. $langcode = field_valid_language($langcode, FALSE);
  254. if (!isset($display_languages[$entity_type][$id][$langcode])) {
  255. $display_language = array();
  256. // By default display language is set to LANGUAGE_NONE if the field
  257. // translation is not available. It is up to translation handlers to
  258. // implement language fallback rules.
  259. foreach (field_info_instances($entity_type, $bundle) as $instance) {
  260. $display_language[$instance['field_name']] = isset($entity->{$instance['field_name']}[$langcode]) ? $langcode : LANGUAGE_NONE;
  261. }
  262. if (field_has_translation_handler($entity_type)) {
  263. $context = array(
  264. 'entity_type' => $entity_type,
  265. 'entity' => $entity,
  266. 'language' => $langcode,
  267. );
  268. drupal_alter('field_language', $display_language, $context);
  269. }
  270. $display_languages[$entity_type][$id][$langcode] = $display_language;
  271. }
  272. $display_language = $display_languages[$entity_type][$id][$langcode];
  273. // Single-field mode.
  274. if (isset($field_name)) {
  275. return isset($display_language[$field_name]) ? $display_language[$field_name] : FALSE;
  276. }
  277. return $display_language;
  278. }