[This is a part of silme tutorial]
The basic unit we use in the localization world is an entity. Entity is a simple object made of ID and a value. ID is a somehow unique identifier of the entity, and the value is an actual string that you want to present to the user.
In Verbatim creating a new Entity looks like this:
from silme.core import Entity entity = Entity('id','value')
This simple object is the most atomic unit in every localization format, be it DTD, Gettext, XLIFF or L20n. It's an abstract representation of a row in the l10n array in SQL or it represents a single string in HTML file (in this case ID has to be a unique identifier of the string position in the file).
Of course Entity may be much more complex than that. In some cases you can have a meta data for the single entity, or a comment that is tied to the entity. Because of how popular those two cases are among l10n formats, Entity object has predefined dictionary objects for those two:
from silme.core import Entity entity = Entity('id','value') entity.params['author'] = 'Ben'
EntityList is a simplest possible class used to store the sequence of entities.
from silme.core import Entity, EntityList entitylist = EntityList() entity1 = Entity('example.id','Test value') entitylist.add_entity(entity1) entity2 = Entity('example.id2','Test value2') entitylist.add_entity(entity2, pos=0) # second argument allows you to define on which position an entity should be added
You can operate on the EntityList to get either all Entities as a new list or just ids of the entities as a new list
from silme.core import EntityList entitylist = EntityList() entity1 = entitylist # returns a first entity from the list entities = entitylist.get_entities() # returns a list of entities entity_id_list = entitylist.get_entity_ids() # returns a list of ids from the entitylist
If you want, you can also change entity or remove it:
from silme.core import EntityList entitylist = EntityList() entitylist.change_entity('entity id', 'new value') entitylist.remove_entity('entity id')
You may assume that the functionality of the Entity and EntityList classes is very basic. Later you'll notice that it makes the use of the library much easier.
An important difference between having a list of Entity objects and having an EntityList object is that in case of EntityList you may define parameters that are defined for the whole list. Another reason is that you may use, and it's preferred, a set of methods to manipulate on the list instead of touching the list directly. The last one is that your code will stay untouched if we'll switch to dictionary as a base class for EntityList in the future.
Below is a bit more complex example of using those two classes
from silme.core import Entity, EntityList entitylist = EntityList() entity1 = Entity('myproject.id1', 'This is an example message') entity2 = Entity('myproject.title', 'App title') entity2.params['type'] = 'Window title' entitylist.add_entity(entity1) entitylist.add_entity(entity2) for entity in entitylist: print entity.value entitylist.change_entity('myproject.id1', 'Changed entity') entitylist.remove_entity('myproject.id1')
Next chapter is about L10nObject and L10nPackage.
You may decide to extend Entity class or just add your own properties to the Entity object.
It would benefit performance and code sleekness to assume that the ID is unique across an EntityList, but the reality is different