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

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

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

On Sun, Jul 26, 2020 at 08:58:11PM +0200, pelzflorian (Florian Pelz) wrote:
> Ohh sorry, the manual disappeared.  I suppose it is built in /srv/…/manual/?

Thank you Ludo for fixing this!

> > Should we publicize a process to contribute translations?  It could be a
> > page on the web site linked from the bottom of each page or something.
> > Thoughts?
> 
> One way would be to tar up the website and send it to the Translation
> Project.  I don’t know about the status of the Weblate plans.

I would suggest sending a tar archive with the website directory of
guix-artwork to the TP once more (ideally along with a current tarball
of Guix proper).  Also I think even if once we use different
technology like Weblate instead of the TP, the TP should remain the
go-to place for our translators, because it is where many other
projects’ translators gather.


> > It would also be nice to have a blog post mentioning this, perhaps
> > explaining the tools behind it, and why we think it matters.  I could
> > contribute a paragraph on linguistic diversity.  :-)
> > 
> > Thanks!
> > 
> > Ludo’.
> 
> So far I think Guix always needs more users and translations help.
> Also Scheme’s homoiconicity makes it easy to write translation macros.
> I will think some more what I could say about this tomorrow.

Please find attached a first draft blog post.

Regards,
Florian

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

title: Adding translations to Guix’ website
date: 2020-07-28 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](/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 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](/manual) and [cookbook](/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
[SHTML](https://www.nongnu.org/guile-lib/doc/ref/htmlprag/), which is
a variant of HTML (in which web pages are usually written) that
integrates well with the [Scheme programming
language](https://schemers.org/).  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 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 strings [the way it is usually done 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>defineddefined<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 [the
Translation Project](https://translationproject.org/team/) or [us Guix
developers](/contact) if you want to help make Guix’ website available
in your language as well!