Improve the translatable documentation

- fix formatting issues
- add translatable example
- explain which fields should go in which entity
Merge pull request #144 from roukmoute/documentation

Improve the translatable documentation