translation-help.asciidoc 5.95 KB
Newer Older
1
2
Pacman - Translating
====================
3
4

This document is here to guide you in helping translate pacman messages,
5
libalpm messages, and the manual pages for the entire pacman package.
6

7
We are currently using https://www.transifex.com/[Transifex] as the translation
Dan McGee's avatar
Dan McGee committed
8
9
platform for pacman and libalpm. You will need to sign up for an account there
and then register with a translation team on the
10
https://www.transifex.com/projects/p/archlinux-pacman/[pacman project page].
11

Dan McGee's avatar
Dan McGee committed
12
13
14
NOTE: This may be old information due to our switch to Transifex, but the
gettext website is a very useful guide to read before embarking on translation
work, as it describes many of the commands in more detail than I will here:
15
https://www.gnu.org/software/gettext/manual/html_node/gettext.html[].
16

17

18
19
20
Translating Messages
--------------------

21
22
23
Overview
~~~~~~~~

24
25
There are two separate message catalogs in pacman: one for the back-end
(libalpm) and one for the front-end (pacman and scripts). These correspond to
26
27
28
29
the `lib/libalpm/po` and `po` directories in the pacman source, respectively.

Translation message files are a specially formatted text file containing the
original message and the corresponding translation. These po files can then
30
either be hand-edited, or modified with a tool such as poedit, gtranslator or
31
32
kbabel. Using a translation tool tends to make the job easier.

Dan McGee's avatar
Dan McGee committed
33
Please read up on Transifex usage using the
34
https://docs.transifex.com/[Transifex Help] if you are not familiar.
Dan McGee's avatar
Dan McGee committed
35

36
37
38
39
Transifex provides a command-line client to help with translations.  Here is
an example set of commands if you have a source code checkout and are not
worried about any local translations being overwritten. The .tx/ directory is
checked into the git repository so is preconfigured with the two project
40
41
resources (See `tx status` output for a quick overview).

Dan McGee's avatar
Dan McGee committed
42
43
44
45
	tx pull -f
	poedit po/<mylang>.po
	poedit lib/libalpm/po/<mylang>.po
	tx push -t -l <mylang>
46
47
48

Or to just push one of the two available resources:

49
50
	tx push -r archlinux-pacman.pacman-pot -t -l <mylang>
	tx push -r archlinux-pacman.libalpm-pot -t -l <mylang>
51

52
53
54
55
56
57
See the <<Notes,Notes>> section for additional hints on translating.

Pre-release Updates
~~~~~~~~~~~~~~~~~~~

A week or two before each release, the codebase will go into a string freeze
Dan McGee's avatar
Dan McGee committed
58
59
60
and an email will be sent to the mailto:pacman-dev@archlinux.org[pacman-dev]
mailing list asking for translations. This email will have a prefix of
*[translation]* for anyone looking to set up an email filter.
61

Dan McGee's avatar
Dan McGee committed
62
At this time, the latest `.po` language files will be made available at the
63
64
Transifex project page.  Each language will have two files available (back-end
and front-end). Translators interested in helping are encouraged to use the
Dan McGee's avatar
Dan McGee committed
65
66
features of Transifex to let others know they are currently translating their
language.
67
68

Once a translator has completed the translation (*OR* realizes they do not have
Dan McGee's avatar
Dan McGee committed
69
time to finish), please upload your progress back to the Transifex site.
70

Dan McGee's avatar
Dan McGee committed
71
72
73
NOTE: Please upload your translations as soon as possible- this will give other
speakers of your language time to review your translations and update them as
necessary.
74
75
76
77
78
79

Incremental Updates
~~~~~~~~~~~~~~~~~~~

If you have more advanced needs you will have to get a copy of the pacman
repository.
80

81
	git clone https://gitlab.archlinux.org/pacman/pacman.git
82
83

Next, you will need to run `./autogen.sh` and `./configure` in the base
84
85
86
directory to generate the correct Makefiles. At this point, all necessary
make targets will be generated and we can begin updating the translation
files.
87

88
89
90
91
We need to first update the main message catalog file. Navigate into either the
`lib/libalpm/po` or `po` directory depending on which translation you wish to
work on first, and execute the following command.  If you are working in the
`po/` tree, replace 'libalpm.pot' with 'pacman.pot':
92

Dan McGee's avatar
Dan McGee committed
93
	make libalpm.pot-update
94

95
Next, update your specific language's translation file:
96

Dan McGee's avatar
Dan McGee committed
97
	make <po file>-update
98

99
100
At this point, you can do the translation. To submit your changes, either email
the new `.po` file to the mailing-list with *[translation]* in the subject, or
101
submit a Git-formatted patch (please do not include any `.pot` file changes).
102
103
104
105

As a shortcut, all translation files (including `.pot` files) can be updated
with the following command:

Dan McGee's avatar
Dan McGee committed
106
	make update-po
107
108
109
110

Adding a New Language
~~~~~~~~~~~~~~~~~~~~~

111
Making a new language is not too hard, but be sure to follow all the steps.
112
113
You will have to do the following steps in both the `lib/libalpm/po/` and `po/`
directories, substituting where appropriate. First, edit the `LINGUAS` file and
114
add your new language code at the bottom. Next, run the following command,
115
116
117
substituting 'libalpm.pot' or 'pacman.pot' for potfile depending on which
directory you are currently working in:

118
119
	msginit -l <lang code> -o <lang code>.po -i <potfile>

120
121
You can then also add your language code to the end of the `LINGUAS` file
located in each po directory.
122

123
124
125
126
127
Look at the current message files for more guidance if necessary. Once you
create the new language file, you may need to slightly modify the headers;
try to make them look similar to the other .po file headers. In addition, for
all new translations we would strongly recommend using UTF-8 encoding.

128
129
Notes[[Notes]]
~~~~~~~~~~~~~~
130

131
msgid and msgstr 'variables' can be on as many lines as necessary. Line breaks
132
are ignored; if you need a literal line break, use an `\n` in your string. The
133
following two translations are equivalent:
Dan McGee's avatar
Dan McGee committed
134

Dan McGee's avatar
Dan McGee committed
135
	msgstr "This is a test translation"
Dan McGee's avatar
Dan McGee committed
136

Dan McGee's avatar
Dan McGee committed
137
138
	msgstr ""
	"This is a test translation"
Dan McGee's avatar
Dan McGee committed
139

140
If you want to test the translation (for example, the front-end one):
141

Dan McGee's avatar
Dan McGee committed
142
143
144
	rm *.gmo stamp-po
	make
	cp <lang code>.gmo /usr/share/locale/<lang code>/LC_MESSAGES/pacman.mo
145

Dan McGee's avatar
Dan McGee committed
146

147
148
Translating Manpages
--------------------
149
150
151
There are currently no efforts underway to include translated manual pages in
the pacman codebase. However, this is not to say translations are unwelcome. If
someone has experience with i18n man pages and how to best include them with our
152
153
source, please contact the pacman-dev mailing list at
mailto:pacman-dev@archlinux.org[].