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 14:36:54 -0000
@@ -3,7 +3,65 @@
 
 /**
  * @file
- * Multilingual field API helper functions.
+ * Functions implementing Field API multilingual support.
+ *
+ * Fields have native multilingual support, as a matter of fact they all share
+ * the following structure:
+ *
+ * $entity->{$field_name}[$langcode][$delta][$column_name]
+ *
+ * This means that every field can hold a (single or multiple) value for each
+ * language belonging to the available languages set.
+ *
+ * - For untranslatable fields this set has cardinality 1 and contains only
+ *   LANGUAGE_NONE.
+ * - For translatable fields this set can contain any language code. By default
+ *   it is the array returned by field_content_languages(), that is the set of
+ *   enabled languages with the addition of LANGUAGE_NONE. This default can be
+ *   altered by modules implementing hook_field_available_languages_alter().
+ *
+ * Translatability is determined by calling field_is_translatable(), which
+ * checks the $field['translatable'] property, where $field is the array
+ * returned by field_info_field(), and the available translation handlers. A
+ * translation handler is a module that registers itself as able to handle field
+ * translations, see hook_entity_info() for details. 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().
+ *
+ * To provide multilingual support, _field_invoke() and _field_invoke_multiple()
+ * act on every language available for the field being processed, unless they
+ * are given a valid language suggestion, which can narrow the available
+ * languages set to a single value. The langugage suggestion is processed by
+ * _field_language_suggestion(), which returns the actual set of languages to
+ * act on.
+ *
+ * Most of field_attach_X() functions act on every available language, however
+ * there are two relevant exceptions which instead act in single-language mode:
+ *
+ * - field_attach_form() just needs a single language code specifying which
+ *   language the field values will be submitted in;
+ * - field_attach_view() needs a requested language, which is the language the
+ *   entity has to be displayed in; however there is no way to be sure that a
+ *   translation in the requested language is available for each field; there
+ *   are two ways to deal with this:
+ *
+ *   1) ignoring missing translations; 
+ *   2) providing an alternative value in a different language, that is language
+ *      fallback; the core behavior is inspecting the field data available in
+ *      the entity to be displayed and determining for each field a language for
+ *      which a translation actually exists; this way a value for each field can
+ *      be displayed.
+ *
+ * For each field the display language is the most fitting language for which a
+ * field value is available, according to the current language fallback
+ * configuration. It can be equal to the requested language, but it will differ
+ * every time a field value for the requested language is not available.
+ * Core language fallback rules inspect all the enabled languages ordered by
+ * their weight, but this behavior can be altered by modules implementing
+ * hook_field_language_alter(), or even disabled, thus making possible to choose
+ * the first approach. The display language for each field attached to an entity
+ * 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.148
diff -u -p -r1.148 system.api.php
--- modules/system/system.api.php	27 Mar 2010 18:41:14 -0000	1.148
+++ modules/system/system.api.php	4 Apr 2010 13:37:27 -0000
@@ -74,6 +74,11 @@ 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 array of module registering themselves as capable to
+ *     handle field translations. Array keys are the module names, array values
+ *     can be any data structure the module uses to provide field translation.
+ *     An empty value does not allow the module to appear as a valid 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
@@ -132,6 +137,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',