Index: modules/field/field.multilingual.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.multilingual.inc,v
retrieving revision 1.10
diff -u -p -r1.10 field.multilingual.inc
--- modules/field/field.multilingual.inc	25 Mar 2010 11:46:20 -0000	1.10
+++ modules/field/field.multilingual.inc	4 Apr 2010 17:56:06 -0000
@@ -3,7 +3,65 @@
 
 /**
  * @file
- * Multilingual field API helper functions.
+ * Functions implementing Field API multilingual support.
+ */
+
+/**
+ * @defgroup field_language Field language API
+ * @{
+ * Handling of multilingual fields.
+ *
+ * Fields natively implement multilingual support, and all fields use the
+ * following structure:
+ * @code
+ * $entity->{$field_name}[$langcode][$delta][$column_name]
+ * @endcode
+ * Every field can hold a single or multiple values for each language belonging
+ * to the available languages:
+ * - Untranslatable fields have a cardinality of 1 and only contain
+ *   LANGUAGE_NONE.
+ * - Translatable fields can contain any language code. By default, it is the
+ *   list returned by field_content_languages(), which contains all enabled
+ *   languages with the addition of LANGUAGE_NONE. This default can be altered
+ *   by modules implementing hook_field_available_languages_alter().
+ *
+ * Whether a field is translatable is determined by calling
+ * field_is_translatable(), which checks the 'translatable' property in the data
+ * returned by field_info_field(), and whether there is a translation handler
+ * available for the field.
+ *
+ * A translation handler is a module that registers itself via
+ * hook_entity_info() to handle field translations. A field is translatable if
+ * its 'translatable' property is set to TRUE and it has at least one available
+ * translation handler.
+ *
+ * The available languages for a particular field are returned by
+ * field_available_languages(). By default, _field_invoke() and
+ * _field_invoke_multiple() are processing a field in all available languages,
+ * unless they are given a language suggestion. Based on that suggestion,
+ * _field_language_suggestion() determines the languages to act on.
+ *
+ * Most of field_attach_*() functions act on all available languages, except for
+ * the following:
+ * - field_attach_form() only takes a single language code, specifying in which
+ *   language the field values will be submitted in.
+ * - field_attach_view() requires a language code the entity is 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
+ *   possible actions:
+ *   - Ignore missing translations, i.e. do not show any field values for the
+ *     requested language. For example, see locale_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().
  */
 
 /**
Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.149
diff -u -p -r1.149 system.api.php
--- modules/system/system.api.php	4 Apr 2010 12:48:18 -0000	1.149
+++ modules/system/system.api.php	4 Apr 2010 17:57:00 -0000
@@ -74,6 +74,10 @@ function hook_hook_info() {
  *     uri elements of the entity, e.g. 'path' and 'options'. The actual entity
  *     uri can be constructed by passing these elements to url().
  *   - fieldable: Set to TRUE if you want your entity type to be fieldable.
+ *   - translation: An associative array of modules registered as field
+ *     translation handlers. Array keys are the module names, array values
+ *     can be any data structure the module uses to provide field translation.
+ *     Any empty value disallows the module to appear as a translation handler.
  *   - entity keys: An array describing how the Field API can extract the
  *     information it needs from the objects of the type. Elements:
  *     - id: The name of the property that contains the primary id of the
@@ -131,6 +135,9 @@ function hook_entity_info() {
       'revision table' => 'node_revision',
       'path callback' => 'node_path',
       'fieldable' => TRUE,
+      'translation' => array(
+        'locale' => TRUE,
+      ),
       'entity keys' => array(
         'id' => 'nid',
         'revision' => 'vid',