← Back to branch summary

~openerp-community/openobject-doc/6.1

« back to all changes in this revision

Viewing changes to source/contribute/documentation_translation.rst

  • Committer: TruongSinh Tran
  • Date: 2009-07-19 19:02:35 UTC
  • Revision ID: truongsinh@vipescoserver-20090719190235-fu3bxcrbpvwuk5h7
https://launchpad.net/bugs/401313
[FIX] build_i18n.py .. raw:: html

Show diffs side-by-side

added added

removed removed

Lines of Context:
source/contribute/documentation_translation.rst
 
1
 
 
2
How to translate the Open Object Documentation in your language
 
3
===============================================================
 
4
 
 
5
Prerequisite
 
6
------------
 
7
 
 
8
You should be able to build the untranslated documentation. So `Sphinx
 
9
<http://sphinx.pocoo.org>`_ should be installed on your system and you should
 
10
know how to use it.
 
11
 
 
12
If this is not the case, please read the `Community Guide's related section
 
13
<http://doc.openerp.com/contribute/documentation_process.html#building-the-documentation>`_.
 
14
 
 
15
You can download the sources of the documentation from launchpad:
 
16
 
 
17
  bzr branch lp:openobject-doc
 
18
 
 
19
 
 
20
Understanding the directory structure
 
21
-------------------------------------
 
22
 
 
23
We are supposing that **<openobject-doc>** is the root of the Open Object
 
24
documentation bazaar branch.
 
25
 
 
26
The *untranslated sources* are located in **<openobject-doc>/source**.
 
27
 
 
28
The translated documentation will be located in **<openobject-doc>>/i18n/<lang>/source**.
 
29
 
 
30
For example, the documentation in french will be
 
31
located in **<openobject-doc>/i18n/fr/source** and it will be built
 
32
in **<openobject-doc>/i18n/fr/build/html** for example.
 
33
 
 
34
Summary
 
35
+++++++
 
36
 
 
37
.. csv-table::
 
38
    :header: "Directory", "Description"
 
39
    :widths: 5,5
 
40
 
 
41
    <openobject-doc>/source,untranslated sources
 
42
    <openobject-doc>/i18n/<lang>/source,translated sources
 
43
    <openobject-doc>/i18n/<lang>/build/html,translated documentation in html
 
44
 
 
45
Creating the translation directory structure
 
46
--------------------------------------------
 
47
 
 
48
Use the **make** command (with target **i18n**) to create the translation
 
49
templates. You'll need to pass the language as an additional parameter to the *make* command.
 
50
 
 
51
For example, supposing you want to translate the documentation in french: ::
 
52
 
 
53
  make i18n LANG=fr
 
54
 
 
55
This command will do several things:
 
56
 
 
57
* create these directories, if they does not exist yet:
 
58
 
 
59
  * i18n
 
60
  * i18n/fr
 
61
  * i18n/fr/source
 
62
  * i18n/fr/build
 
63
 
 
64
* copy files in *i18n/fr/* required for the html build:
 
65
 
 
66
  * MakeFile
 
67
  * conf.py
 
68
 
 
69
* create the *translation templates* based on the untranslated restructured text files. They will be created in *i18n/fr/source*
 
70
 
 
71
* copy all the other necessary files (images for example)
 
72
 
 
73
 
 
74
Translation templates
 
75
---------------------
 
76
 
 
77
The template structure for a given file is very simple. Each text section is
 
78
prepended by the original context. Here is a title, for example: ::
 
79
 
 
80
  .. i18n: %%%%%%%%%%%%%%%%%%%%%%%%%
 
81
  .. i18n: Open Object Documentation
 
82
  .. i18n: %%%%%%%%%%%%%%%%%%%%%%%%%
 
83
 
 
84
  %%%%%%%%%%%%%%%%%%%%%%%%%
 
85
  Open Object Documentation
 
86
  %%%%%%%%%%%%%%%%%%%%%%%%%
 
87
 
 
88
The context is a commented section starting with **.. i18n:**. It helps you
 
89
understand the section in its context. It also helps you remember the original
 
90
section.
 
91
 
 
92
And here is the translated section: ::
 
93
 
 
94
  .. i18n: %%%%%%%%%%%%%%%%%%%%%%%%%
 
95
  .. i18n: Open Object Documentation
 
96
  .. i18n: %%%%%%%%%%%%%%%%%%%%%%%%%
 
97
 
 
98
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
99
  Documentation sur Open Object
 
100
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
101
 
 
102
Managing source changes
 
103
-----------------------
 
104
 
 
105
If someone adds or changes something in the documentation, that section will
 
106
have to be retranslated but all the other sections will hopefully keep their
 
107
translation.
 
108
 
 
109
When you will get the documentation changes with bzr pull (for example), the
 
110
new sections and some changed sections will be reset to the untranslated text
 
111
when you will rebuild the translation with *make i18n LANG=fr*.
 
112
 
 
113
Building the documentation in your language
 
114
-------------------------------------------
 
115
 
 
116
That is very simple because the directory and file structure is exactly the
 
117
same as the original structure: ::
 
118
 
 
119
  i18n
 
120
  `-- fr
 
121
      |-- build
 
122
      `-- source
 
123
 
 
124
For example, in *i18n/fr*, you just have to do a simple *make*::
 
125
 
 
126
  make html
 
127
 
 
128
And the html documentation will be built in *i18n/fr/build/html*.
 
129
 
 
130
Uploading to Launchpad
 
131
----------------------
 
132
 
 
133
Once you have translated a few pages, you should commit back to launchpad.
 
134
To do this, your launchpad account must be subscribed in the 
 
135
`openobject-community group <http://https://launchpad.net/~openerp-community>`_.
 
136
 
 
137
To upload your modifications, you should commit on launchpad:
 
138
 
 
139
  bzr add YOUR_NEW_FILES_OR_DIR
 
140
  bzr ci
 
141
  bzr push
 
142
 
 
143
Status
 
144
------
 
145
 
 
146
At the moment, this script is in alpha status and has not been thoroughly
 
147
tested. It should work but expect some bugs to pop up at unexpected times.
 
148
Contact oli AT openerp.com if you notice some troubles.
 
149
 
 
150