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 <eschwartz@archlinux.org>
Signed-off-by: Allan McRae <allan@archlinux.org>

1 files changed, 153 insertions, 0 deletions

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/<mylang>.po
+	poedit lib/libalpm/po/<mylang>.po
+	tx push -t -l <mylang>
+
+Or to just push one of the two available resources:
+
+	tx push -r archlinux-pacman.pacman-pot -t -l <mylang>
+	tx push -r archlinux-pacman.libalpm-pot -t -l <mylang>
+
+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
+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 <po file>-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 <lang code> -o <lang code>.po -i <potfile>
+
+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 <lang code>.gmo /usr/share/locale/<lang code>/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[].