Commits

Florent Cayré committed 06c086d

a bit of documentation

Comments (0)

Files changed (3)

 Summary
 -------
-Provides a way to translate entity fields individually.
+
+This cube provides a way to manage and display entity field (attribute)
+translations, stored in the application database.
+
+To achieve this for your particular entity type, you have to:
+
+* add an 'i18nfield_of' relation definition, linking from the 'I18nField'
+entity type to your translatable entity type(s)
+
+* add a 'ref_lang' relation definition, linking from your entity types
+to the 'Language' entity type
+
+* make your business entity type inherit the 'TranslatableEntityMixin' and
+list its translatable fields in its 'i18nfields' attribute
+
+* create a simple adapter that inherits '_TranslatableEntityAdapter' and is
+selectable for your translatable entity types
+
+That's all for the code part. Just add at least one Language instance in your
+database and link your translatable entities to their reference language.
+
+The default web UI will then display a new 'translations' action menu to
+users who can modify translatable entities, and display your translatable
+entities in the web request language by default.
+
+Example
+-------
+
+If you want to translate all fields of the Card entity type (from the 'card'
+cube), you will need in your schema.py file:
+
+.. sourcecode:: python
+
+ from yams.buildobjs import RelationDefinition
+ 
+ 
+ class i18nfield_of(RelationDefinition):
+     subject = 'I18nField'
+     object = 'Card'
+     cardinality = '1*'
+     composite = 'object'
+ 
+ 
+ class ref_lang(RelationDefinition):
+     subject = 'Card'
+     object = 'Language'
+     cardinality = '1*'
+     inlined = True
+
+
+And in the entities.py file:
+
+.. sourcecode:: python
+
+ from cubicweb.selectors import yes, is_instance
+ 
+ from cubes.card.entities import Card as OrigCard
+ from cubes.i18nfield.entities import (TranslatableEntityMixin,
+                                       _TranslatableEntityAdapter)
+ 
+ 
+ class Card(TranslatableEntityMixin, OrigCard):
+     __select__ = OrigCard.__select__ & yes()
+     i18nfields = (u'title', u'synopsis', u'content')
+ 
+     def dc_title(self):
+         return self.printable_value('title', format='text/plain')
+ 
+ 
+ class MyTranslatableEntityAdapter(_TranslatableEntityAdapter):
+     __select__ = _TranslatableEntityAdapter.__select__ & is_instance('Card')
 # You should have received a copy of the GNU Lesser General Public License along
 # with this program. If not, see <http://www.gnu.org/licenses/>.
 
-"""cubicweb-i18nfield entity's classes
-
-Application cubes must implement the 2 following classes to enable field-level
-i18n for one schema:
-
-* the specific AnyEntity child class of the schema must inherit the
-`TranslatableEntityMixin` class and implement the `i18nfields` attribute
-
-* an adapter that inherits from _TranslatableEntityAdapter and is selectable
-with for the translatable entity type
-
-See test/data/entities.py for an example.
-
-"""
+"""cubicweb-i18nfield entity's classes"""
 
 from logilab.common.decorators import cached
 
 # You should have received a copy of the GNU Lesser General Public License along
 # with this program. If not, see <http://www.gnu.org/licenses/>.
 
-"""cubicweb-i18nfield schema
-
-This schema must be completed by application cubes, by adding a i18nfield_of
-RelationDefinition from I18nField to translatable entity types.
-
-Business objects must also implement things (see entities.py doc).
-"""
+"""cubicweb-i18nfield schema"""
 
 
 from yams.buildobjs import (EntityType, RelationType, RelationDefinition,