bug#26302: Multilingual web site is on-line!

["pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de>]

[-- Attachment #1: Type: text/plain, Size: 1338 bytes --]

On Fri, Jul 31, 2020 at 04:45:31PM +0200, Ludovic Courtès wrote:
> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:
> > On Tue, Jul 28, 2020 at 11:50:13PM +0200, Ludovic Courtès wrote:
> >> I wonder if we should link to more practical step-by-step instructions
> >> on how to get started translating, to lower the barrier for those who
> >> want to get started without engaging in possibly open-ended discussions
> >> with the fabulous Guix team.  :-)
> > I don’t know how best to integrate step-by-step instructions.  While
> > the TP has instructions
> > <https://translationproject.org/html/translators.html>, they seem more
> > intimidating to me than, as a first step, talking to the helpful
> > people at the TP.  A few steps also describe how to disclaim
> > copyright, which Guix does not ask for anyway.
> Yeah, dunno.  In the post you could duplicate/filter those steps just so
> it’s more directly understandable what it takes to translate pages.
> Your call!

I rewrote the part for translators that comes before the first source
code in the post and changed it again and again while a
not-yet-Guix-using friend gave helpful feedback.  I attach the current
draft blog post, but currently you can also read it at:

https://pelzflorian.de/adding-translations-to-guix-website/index.html

Regards,
Florian

[-- Attachment #2: 3rd-draft-adding-translations-to-guix-website.md --]
[-- Type: text/markdown, Size: 6664 bytes --]

title: Adding translations to Guix’ website
date: 2020-08-01 15:00
author: Florian Pelz
tags: Community
---
As part of [GNU](https://www.gnu.org), Guix aims to bring freedom to
computer users all over the world, no matter the languages they
(prefer to) speak.  For example, Guix users asking for
[help](https://guix.gnu.org/help) can expect an answer even if they do
so in languages other than English.

We also offer translated software for people more comfortable with a
language other than English.  Thanks to many people who contribute
translations, GNU Guix and the packages it distributes can be used in
various languages, which we value greatly.  We are happy to announce
that Guix’ website can now be translated in the same manner.  If you
want to get a glimpse on how the translation process works, first from
a translator’s, then from a programmer’s perspective, read on.

The process for translators is kept simple.  Like lots of other free
software packages, Guix uses
[GNU Gettext](https://www.gnu.org/software/gettext) for its
translations, with which translatable strings are extracted from the
source code to so-called PO files.  If this is new to you, the magic
behind the translation process is best understood by taking a look at
one of them.  Download a PO file from [your language’s team at the
Translation Project (TP)](https://translationproject.org/team).

Even though PO files are text files, changes should not be made with a
text editor but with PO editing software.  Translators can use any of
various free-software tools for filling in translations, of which
[Poedit](https://poedit.net) is one example.  There also is a [special
PO editing mode](https://www.emacswiki.org/emacs/PoMode) for users of
[GNU Emacs](https://www.gnu.org/software/emacs).  Over time
translators find out what software they are happy with and what
features they need.

Help with translations is much appreciated.  If you intend to become a
translator, before you begin with serious editing of a PO file, you
should learn about how your TP team is organized.  You need to talk to
[your team](https://translationproject.org/team) at the Translation
Project, which also helps avoid duplicate work.  The TP also hosts a
[list of steps](https://translationproject.org/html/translators.html)
to help new translators getting started, though not all are needed for
Guix — we at Guix do not require a copyright disclaimer — and it may
be easier to talk to the helpful people at your TP team.

So much for the translation of ordinary source code.  With
[Po4a](https://po4a.org), we can also use Gettext’s tooling to
translate Guix’ [manual](https://guix.gnu.org/manual/) and
[cookbook](https://guix.gnu.org/cookbook/).  But all this was not true
of its web presence.  That’s why after a [lengthy
process,](https://issues.guix.info/issue/26302) the website of
GNU Guix has undergone an update.  It now supports translation into
other languages.  Such support is known as internationalization
(“i18n”).

Guix’ website is written in a variant of HTML (in which web pages are
usually written) that integrates better with the [Scheme programming
language](https://schemers.org).  Instead of XML tags, we use
[SXML](https://www.gnu.org/software/guile/manual/html_node/SXML.html).
This allows web authors to mix code and text.  It looks like this:

```scheme
`(section
  (h2 "On packaging")
  (p
   "Packages are "
   (a (@ (href ,(manual-url "Defining-Packages.html"))) "defined")
   " as native "
   (a (@ (href ,(gnu-url "software/guile"))) "Guile")
   " modules."))
```

However, this mixing makes it more difficult to extract the strings to
be translated.  We therefore cannot take the same approach as
[gnu.org](https://www.gnu.org), which uses a software package called
[GNUnited Nations](https://www.gnu.org/software/gnun) to extract from
pure HTML mark-up.  Translators are not always coders and we would
prefer to show them only the textual part, like this:

```
msgid "Packages are <1>defined</1> as native <2>Guile</2> modules."
```

Our new, custom i18n system does this.  The website authors need to
mark translatable expressions in the same way ordinary strings are
[usually marked in Guile Scheme
programs:](https://www.gnu.org/software/guile/manual/html_node/Gettext-Support.html#Gettext-Support)

```scheme
`(section
  ,(G_ `(h2 "On packaging"))
  ;; TRANSLATORS: Defining Packages is a section name
  ;; in the English (en) manual.
  ,(G_ `(p
         "Packages are "
         ,(G_ (manual-href "defined" (G_ "en") (G_ "Defining-Packages.html")))
         " as native "
         ,(G_ `(a (@ (href ,(gnu-url "software/guile"))) "Guile"))
         " modules.")))
```

Translators can arbitrarily change the ordering:

```
#. TRANSLATORS: Defining Packages is a section name
#. in the English (en) manual.
#: apps/base/templates/about.scm:64
msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
```

Details are [documented
here](https://git.savannah.gnu.org/cgit/guix/guix-artwork.git/tree/website/i18n-howto.txt).
We hope it strikes the right balance between simplicity for the
website’s developers and translator comfort.  Still missing is a way
to translate blog posts like the one you are reading here.

With ideas for and by a more diverse community, we can look forward to
a bright multi-lingual future.  Please get in touch with [your
language’s team](https://translationproject.org/team) or [us Guix
developers](https://guix.gnu.org/contact) if you want to help make
Guix’ website available in your language as well!

#### About GNU Guix

[GNU Guix](https://guix.gnu.org) is a transactional package
manager and an advanced distribution of the GNU system that [respects
user
freedom](https://www.gnu.org/distros/free-system-distribution-guidelines.html).
Guix can be used on top of any system running the kernel Linux, or it
can be used as a standalone operating system distribution for i686,
x86_64, ARMv7, and AArch64 machines.

In addition to standard package management features, Guix supports
transactional upgrades and roll-backs, unprivileged package management,
per-user profiles, and garbage collection.  When used as a standalone
GNU/Linux distribution, Guix offers a declarative, stateless approach to
operating system configuration management.  Guix is highly customizable
and hackable through [Guile](https://www.gnu.org/software/guile)
programming interfaces and extensions to the
[Scheme](https://schemers.org) language.