1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
---
layout: page
title: Translation
---
# Translating Alaveteli
<p class="lead">
We've designed Alaveteli to be used in many different
jurisdictions all around the world. If it doesn't already
support the language you need, you can help by translating
it. This page explains how.
</p>
## Alaveteli already contains translations!
Alaveteli ships ready to run in a number of different languages.
If Alaveteli has already been translated into the language (or languages) you
need, you just need to configure it -- see
[`AVAILABLE_LOCALES`]({{ page.baseurl }}/docs/customising/config/#available_locales).
[Look in the `locale/` directory](https://github.com/mysociety/alaveteli/tree/master/locale)
to see what translations are already available. Some are complete
translations of the site. Others are only partial -- either because the translations
have not been finished yet, or else because the translators have not updated the
texts since developers changed or added text on the site.
There are two reasons the translations may need more work before you can use them:
* **the language you want is not one of those we already have** <br> In this
case, there will be no entry in ``locale/`` for it, because nobody has yet
translated Alaveteli into your language. See the rest of this page to learn
how to add a new translation.
* **the translation for your language is incomplete, or lagging behind** <br>
This might simply be because it is a work in progress. Furthermore, sometimes
an incomplete translation already covers all the areas of the site you need
anyway. Of course, you can add to a partial translation, but it's a good idea
to check with us first, since we'll probably know who is working on the
current translation and what state it's in.
Translators are members of the Alaveteli
[community]({{ page.baseurl }}/community/), and often work separately from the
developers. This means translations can lag a little behind the code. However,
our release process includes a "translation freeze", which gives the
translators a chance to catch up -- read the rest of this page for details.
## Alaveteli's translations
You don't need to be a programmer to translate Alaveteli -- we use an external
website called <a href="{{ page.baseurl }}/docs/glossary/#transifex" class="glossary__link">Transifex</a> to help manage translations. This makes it easy for
translators to get to work, but it does mean you (or your technical team)
need to do a little extra work to get those translations back into Alaveteli
when they are ready.
The Transifex project is at
[https://www.transifex.com/projects/p/alaveteli](https://www.transifex.com/projects/p/alaveteli)
-- you'll probably want an account there (ask on the mailing list). It has a
fairly easy-to-use interface for contributing translations.
Alaveteli localises strings using GNU gettext and
<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link"><code>.pot</code> & <code>.po</code> files</a>.
If you're a developer, you should read
[internationalising Alaveteli]({{ page.baseurl }}/docs/developers/i18n/).
## What a translator needs to do
**If you're just working on translating Alaveteli into a language you know, then
this section is for you.**
> Remember that Alaveteli
> [already comes with some translations](#alaveteli-already-contains-translations),
> so check first that you really need to do this. Maybe someone has already
> translated Alaveteli into the language you need!
When a developer adds a new feature to the user interface in Alaveteli, they
use some code to mark sentences or words ("strings") that they think will need
to be translated.
When the Alaveteli
<a href="{{ page.baseurl }}/docs/glossary/#release" class="glossary__link">release manager</a>
is planning a release, they will upload a
template containing all the strings to be translated (called a
<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link"><code>.pot</code> file</a>)
to Transifex. This causes your own translations in Transifex to be updated with
the latest strings.
When you visit Transifex, it will prompt you to fill out values for all new
strings, and all strings that have been modified. In the case where a string
has only been slightly modified, such as with punctuation ("Hello" has become
"Hello!"), Transifex will suggest a suitable translation for you (look for the
*Suggestions* tab under the source string).
In order for this feature to work properly, the release manager has to download
your translations, run a program that inserts the suggestions, and then upload
them again. Therefore, when a release candidate is announced, make sure you
have uploaded any outstanding translations, or you will lose them.
When a release candidate has been annouced, there is a **translation freeze**:
during this period, developers must not add any new strings to the software, so
you can be confident that you're translating everything that will be in the
final release.
The release manager will also give you a **translation deadline**. After this
date, you can continue to contribute new translations, but they won't make it
into the release.
### General notes on translation in Transifex
Some strings will have comments attached to them from the Alaveteli
application developers about the context in which the text appears in the
application — these comments will appear under the *Details* tab for the text
in Transifex.
Some strings will have **placeholders** in them to indicate that Alaveteli
will insert some text of its own into them when they're displayed. They
will be surrounded by double curly brackets, and look like this:
<code>
some text with {{placeholder}} in it
</code>
For these strings, don't translate the placeholder. It needs to stay exactly
the same for the text to be inserted properly:
<code>
ein Text mit {{placeholder}} in ihm
</code>
Similarly, some strings may contain small bits of HTML — these will have
code in angle brackets (it might really be indicating that the text is a link,
or that it needs special formatting). For example:
<code>
please <a href=\"{{url}}\">send it to us</a>
</code>
Again, don't edit the bits between the angle brackets — preserve them in your
translation, and just edit the text around them. So the example might become:
<code>
bitte <a href=\"{{url}}\">schicken Sie es uns</a>
</code>
Some strings are in the form of two pieces of text separated by a vertical
bar (`|`) character, e.g. `IncomingMessage|Subject`. These represent attribute
names, so `IncomingMessage|Subject` is the subject attribute of an incoming
message on the site. Do not prioritise these types of text when translating --
they do not appear on the site anywhere at the moment, and when they do, they
will only be used in the admin interface. If you do translate them, only
translate the text that comes *after* the `|`.
## How the translations get into Alaveteli
In order to get the translated strings from Transifex into Alaveteli, follow
the instructions in these [deployment notes]({{ page.baseurl }}/docs/developers/i18n/#deployment-notes).
This will be the job of the technical people on your team (or
even mySociety's release manager). If translators aren't technical, they can
use Transifex without needing to worry about this.
## The help pages
As the help pages for Alaveteli contain lots of text, they're translated
outside Transifex, by translating each whole help page and replacing it
in the theme that Alaveteli is using, so that it overrides the default
page. See the [guide to Alaveteli's themes]({{ page.baseurl }}/docs/customising/themes/#customising-the-help-pages) for more
information on this.
## Developers and internationalisation
If you're writing new code for Alaveteli, then you're a developer, and you
need to understand how to make any text you add easy for translators to work
with -- see the page about
[internationalising Alaveteli]({{ page.baseurl }}/docs/developers/i18n/).
If you are a developer or translator actively working on internationalising
Alaveteli code, you should talk to us to find out when the next release is due,
so your translations can be prepared in time to be included in it.
|
