From 076b6184de2b20e9b26225d93f6f3a7030504109 Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Thu, 3 May 2018 00:10:21 -0400 Subject: Ensure better text editor automatic filetype detection Since we no longer use vim-specific modelines, use the .asciidoc file extension which is, well, reserved for asciidoc formatted files. This should presumably work everywhere without needing editor-specific workarounds and configuration. Also add a shebang to makepkg.conf to indicate it contains bash content. Signed-off-by: Eli Schwartz Signed-off-by: Allan McRae --- doc/translation-help.asciidoc | 153 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 doc/translation-help.asciidoc (limited to 'doc/translation-help.asciidoc') diff --git a/doc/translation-help.asciidoc b/doc/translation-help.asciidoc new file mode 100644 index 00000000..67117bcc --- /dev/null +++ b/doc/translation-help.asciidoc @@ -0,0 +1,153 @@ +Pacman - Translating +==================== + +This document is here to guide you in helping translate pacman messages, +libalpm messages, and the manual pages for the entire pacman package. + +We are currently using http://www.transifex.com/[Transifex] as the translation +platform for pacman and libalpm. You will need to sign up for an account there +and then register with a translation team on the +http://www.transifex.com/projects/p/archlinux-pacman/[pacman project page]. + +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: +https://www.gnu.org/software/gettext/manual/html_node/gettext.html[]. + + +Translating Messages +-------------------- + +Overview +~~~~~~~~ + +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 +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 +either be hand-edited, or modified with a tool such as poedit, gtranslator or +kbabel. Using a translation tool tends to make the job easier. + +Please read up on Transifex usage using the +http://docs.transifex.com/[Transifex Help] if you are not familiar. + +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 +resources (See `tx status` output for a quick overview). + + tx pull -f + poedit po/.po + poedit lib/libalpm/po/.po + tx push -t -l + +Or to just push one of the two available resources: + + tx push -r archlinux-pacman.pacman-pot -t -l + tx push -r archlinux-pacman.libalpm-pot -t -l + +See the <> section for additional hints on translating. + +Pre-release Updates +~~~~~~~~~~~~~~~~~~~ + +A week or two before each release, the codebase will go into a string freeze +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. + +At this time, the latest `.po` language files will be made available at the +Transifex project page. Each language will have two files available (back-end +and front-end). Translators interested in helping are encouraged to use the +features of Transifex to let others know they are currently translating their +language. + +Once a translator has completed the translation (*OR* realizes they do not have +time to finish), please upload your progress back to the Transifex site. + +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. + +Incremental Updates +~~~~~~~~~~~~~~~~~~~ + +If you have more advanced needs you will have to get a copy of the pacman +repository. + + git clone git://projects.archlinux.org/pacman.git pacman + +Next, you will need to run `./autogen.sh` and `./configure` in the base +directory to generate the correct Makefiles. At this point, all necessary +make targets will be generated and we can begin updating the translation +files. + +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': + + make libalpm.pot-update + +Next, update your specific language's translation file: + + make -update + +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 +submit a Git-formatted patch (please do not include any `.pot` file changes). + +As a shortcut, all translation files (including `.pot` files) can be updated +with the following command: + + make update-po + +Adding a New Language +~~~~~~~~~~~~~~~~~~~~~ + +Making a new language is not too hard, but be sure to follow all the steps. +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 +add your new language code at the bottom. Next, run the following command, +substituting 'libalpm.pot' or 'pacman.pot' for potfile depending on which +directory you are currently working in: + + msginit -l -o .po -i + +You can then also add your language code to the end of the `LINGUAS` file +located in each po directory. + +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. + +Notes[[Notes]] +~~~~~~~~~~~~~~ + +msgid and msgstr 'variables' can be on as many lines as necessary. Line breaks +are ignored; if you need a literal line break, use an `\n` in your string. The +following two translations are equivalent: + + msgstr "This is a test translation" + + msgstr "" + "This is a test translation" + +If you want to test the translation (for example, the front-end one): + + rm *.gmo stamp-po + make + cp .gmo /usr/share/locale//LC_MESSAGES/pacman.mo + + +Translating Manpages +-------------------- +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 +source, please contact the pacman-dev mailing list at +mailto:pacman-dev@archlinux.org[]. -- cgit v1.2.3-70-g09d2