On Tue, Jul 28, 2020 at 11:50:13PM +0200, Ludovic Courtès wrote: > "pelzflorian (Florian Pelz)" <[email protected]> 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
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.
