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

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

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

On Tue, Jul 28, 2020 at 11:50:13PM +0200, Ludovic Courtès wrote:
> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:
> > Guix’ website is written in
> > [SHTML](https://www.nongnu.org/guile-lib/doc/ref/htmlprag/), which is
> > a variant of HTML (in which web pages are usually written) that
> 
> I think it’s technically SXHTML, no?
> https://www.gnu.org/software/guile/manual/html_node/SXML.html

The result is not valid XHTML.  I will just call it SXML now, which is
what the Haunt info manual calls it.


> 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.

I propose the attached blog post draft if noone objects, taking into
account Ludo’s helpful suggestions.  Is it missing anything
interesting about the i18n system?

Should I add it to the website as a draft?  I suppose no, I suppose I
should just publish it as-is once guix-website.pot is at the TP.

Regards,
Florian

[-- Attachment #2: 2nd-draft-blog-post-translatable-website.md --]
[-- Type: text/markdown, Size: 5146 bytes --]

title: Adding translations to Guix’ website
date: 2020-07-29 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 software translations 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.  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.  Translators can use any of various
free-software tools, such as
[GNU Emacs](https://www.gnu.org/software/emacs) or
[Poedit](https://poedit.net), for filling in translations.  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 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) at the
[Translation Project](https://translationproject.org) 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.