Field Language API

Handles multilingual fields.

Fields natively implement multilingual support, and all fields use the following structure:

$entity->{$field_name}[$langcode][$delta][$column_name];

Every field can hold a single or multiple value for each language code belonging to the available language codes set:

• For untranslatable fields this set only contains LANGUAGE_NOT_SPECIFIED.
• For translatable fields this set can contain any language code. By default it is the list returned by field_content_languages(), which contains all installed languages with the addition of LANGUAGE_NOT_SPECIFIED. This default can be altered by modules implementing hook_field_available_languages_alter().

The available language codes for a particular field are returned by field_available_languages(). Whether a field is translatable is determined by calling field_is_translatable(), which checks the $field['translatable'] property returned by field_info_field(), and whether there is at least one translation handler available for the field. A translation handler is a module registering itself via hook_entity_info_alter() to handle field translations.

By default, _field_invoke() and _field_invoke_multiple() are processing a field in all available languages, unless they are given a language code suggestion. Based on that suggestion, _field_language_suggestion() determines the languages to act on.

By default, _field_invoke() and _field_invoke_multiple() process a field in all available languages, unless they are given a language code suggestion. Based on that suggestion, _field_language_suggestion() determines the languages to act on.

Most field_attach_*() functions act on all available language codes, except for the following:

• field_attach_form() only takes a single language code, specifying which language the field values will be submitted in.
• field_attach_view() requires the language the entity will be displayed in. Since it is unknown whether a field translation exists for the requested language, the translation handler is responsible for performing one of the following actions:
  • Ignore missing translations, i.e. do not show any field values for the requested language. For example, see field_field_language_alter().
  • Provide a value in a different language as fallback. By default, the fallback logic is applied separately to each field to ensure that there is a value for each field to display.

  The field language fallback logic relies on the global language fallback configuration. Therefore, the displayed field values can be in the requested language, but may be different if no values for the requested language are available. The default language fallback rules inspect all the enabled languages ordered by their weight. This behavior can be altered or even disabled by modules implementing hook_field_language_alter(), making it possible to choose the first approach. The display language for each field is returned by field_language().

See Field API for information about the other parts of the Field API.

File

drupal/core/modules/field/field.multilingual.inc, line 8

Functions implementing Field API multilingual support.

Functions

Name	Location	Description
field_available_languages	drupal/core/modules/field/field.multilingual.inc	Collects the available language codes for the given entity type and field.
field_content_languages	drupal/core/modules/field/field.multilingual.inc	Returns available content language codes.
field_has_translation_handler	drupal/core/modules/field/field.multilingual.inc	Checks if a module is registered as a translation handler for a given entity.
field_is_translatable	drupal/core/modules/field/field.multilingual.inc	Checks whether a field has language support.
field_language	drupal/core/modules/field/field.multilingual.inc	Returns the display language code for the fields attached to the given entity.
field_language_delete	drupal/core/modules/field/field.multilingual.inc	Implements hook_language_delete().
field_language_insert	drupal/core/modules/field/field.multilingual.inc	Implements hook_language_insert().
field_language_update	drupal/core/modules/field/field.multilingual.inc	Implements hook_language_update().
field_valid_language	drupal/core/modules/field/field.multilingual.inc	Ensures that a given language code is valid.
_field_language_suggestion	drupal/core/modules/field/field.multilingual.inc	Process the language code suggestion based on the available language codes.