unofficial mirror of bug-guix@gnu.org 
 help / color / mirror / code / Atom feed
From: "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: Daniela Lura <danielaluraa@gmail.com>,
	sirgazil <sirgazil@zoho.com>, 26302 <26302@debbugs.gnu.org>
Subject: bug#26302: Multilingual web site is on-line!
Date: Wed, 29 Jul 2020 21:21:03 +0200	[thread overview]
Message-ID: <20200729192103.2fug7t6to2tuiwew@pelzflorian.localdomain> (raw)
In-Reply-To: <87k0yns416.fsf@gnu.org>

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

  parent reply	other threads:[~2020-07-29 19:22 UTC|newest]

Thread overview: 95+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-03-29 15:40 bug#26302: [website] translations ng0
2017-03-29 16:13 ` ng0
2017-04-15 12:00   ` ng0
2017-04-15 12:26     ` ng0
2017-07-31 21:11 ` Ludovic Courtès
2017-07-31 21:54   ` ng0
2019-09-06 14:25     ` pelzflorian (Florian Pelz)
2019-09-06 14:42       ` pelzflorian (Florian Pelz)
2019-09-08 19:44       ` Ludovic Courtès
2019-09-08 20:46         ` pelzflorian (Florian Pelz)
2019-09-18 13:57       ` Ludovic Courtès
2019-09-19  7:48         ` pelzflorian (Florian Pelz)
2019-09-19 11:42           ` bug#26302: Adding Florian as a committer Ludovic Courtès
2019-09-19 11:50           ` bug#26302: [website] translations Ludovic Courtès
2019-09-19 22:08             ` pelzflorian (Florian Pelz)
2019-10-22 12:10             ` Ludovic Courtès
2019-10-22 12:28               ` pelzflorian (Florian Pelz)
2019-10-22 12:41                 ` pelzflorian (Florian Pelz)
2019-10-23 14:16                   ` Ludovic Courtès
2019-10-23 14:41                     ` pelzflorian (Florian Pelz)
2019-10-22 13:01                 ` pelzflorian (Florian Pelz)
2019-10-31 20:19                 ` pelzflorian (Florian Pelz)
2019-11-01 14:58                   ` Ludovic Courtès
2019-09-06 18:17 ` sirgazil via Bug reports for GNU Guix
2019-09-08 17:16   ` pelzflorian (Florian Pelz)
2019-09-10  0:49     ` sirgazil via Bug reports for GNU Guix
2019-09-15 20:18       ` pelzflorian (Florian Pelz)
2019-09-18 13:00         ` pelzflorian (Florian Pelz)
2019-10-07  8:15         ` pelzflorian (Florian Pelz)
2019-10-08  9:37           ` pelzflorian (Florian Pelz)
2019-11-08  9:02             ` pelzflorian (Florian Pelz)
2019-11-08 14:01               ` sirgazil via Bug reports for GNU Guix
2019-11-08 16:18                 ` pelzflorian (Florian Pelz)
2019-11-08 16:20                   ` pelzflorian (Florian Pelz)
2019-11-08 17:13                   ` pelzflorian (Florian Pelz)
2019-11-08 18:39                     ` sirgazil via Bug reports for GNU Guix
2019-11-17 16:17             ` pelzflorian (Florian Pelz)
2019-12-02  8:57               ` pelzflorian (Florian Pelz)
2020-03-25 17:33               ` bug#26302: Deploying the i18n’d web site Ludovic Courtès
2020-03-25 23:21                 ` pelzflorian (Florian Pelz)
2020-03-26  1:24                   ` pelzflorian (Florian Pelz)
2020-04-07 21:18                   ` Ludovic Courtès
2020-04-07 22:02                     ` pelzflorian (Florian Pelz)
2020-04-09  3:21                       ` pelzflorian (Florian Pelz)
2020-04-09  7:45                         ` pelzflorian (Florian Pelz)
2020-04-09 14:57                           ` pelzflorian (Florian Pelz)
2020-04-09 15:27                             ` Ludovic Courtès
2020-04-09 17:31                               ` pelzflorian (Florian Pelz)
2020-04-09 18:58                                 ` Bengt Richter
2020-04-09 19:17                                   ` pelzflorian (Florian Pelz)
2020-07-01 20:11                                     ` Christopher Baines
2020-07-05  9:08                                 ` pelzflorian (Florian Pelz)
2020-07-09 13:09                                   ` Ludovic Courtès
2020-07-09 14:48                                     ` pelzflorian (Florian Pelz)
2020-07-10 17:28                                       ` pelzflorian (Florian Pelz)
2020-07-12  6:26                                         ` pelzflorian (Florian Pelz)
2020-07-26 17:46                                           ` bug#26302: Multilingual web site is on-line! Ludovic Courtès
2020-07-26 18:57                                             ` pelzflorian (Florian Pelz)
2020-07-27 16:01                                               ` pelzflorian (Florian Pelz)
2020-07-28 21:50                                                 ` Ludovic Courtès
2020-07-29  1:21                                                   ` Julien Lepiller
2020-07-29 13:56                                                     ` pelzflorian (Florian Pelz)
2020-08-03 14:53                                                       ` Ludovic Courtès
2020-08-21  0:14                                                         ` pelzflorian (Florian Pelz)
2020-08-21  0:41                                                           ` Julien Lepiller
2020-08-21  7:51                                                             ` pelzflorian (Florian Pelz)
2020-07-29 19:21                                                   ` pelzflorian (Florian Pelz) [this message]
2020-07-31 14:45                                                     ` Ludovic Courtès
2020-08-04 15:37                                                       ` pelzflorian (Florian Pelz)
2020-08-23 15:55                                                         ` Ludovic Courtès
2020-08-24 12:47                                                           ` pelzflorian (Florian Pelz)
2020-08-24 14:05                                                             ` Ludovic Courtès
2020-07-27  1:54                                             ` Dmitry Alexandrov
2020-07-27 11:28                                               ` pelzflorian (Florian Pelz)
2020-07-27 20:20                                                 ` pelzflorian (Florian Pelz)
2020-07-09 16:56                                   ` bug#26302: Deploying the i18n’d web site Christopher Baines
2020-07-10 17:31                                     ` pelzflorian (Florian Pelz)
2020-07-13 13:22                                       ` Ludovic Courtès
2020-07-13 14:48                                         ` pelzflorian (Florian Pelz)
2020-07-13 16:32                                           ` pelzflorian (Florian Pelz)
2019-11-01 14:54           ` bug#26302: [website] translations Ludovic Courtès
2019-11-02 13:15             ` pelzflorian (Florian Pelz)
2019-11-04 17:19               ` Ludovic Courtès
2019-11-05  7:31                 ` pelzflorian (Florian Pelz)
2019-11-05 11:11                   ` pelzflorian (Florian Pelz)
2019-11-06 14:56                     ` Ludovic Courtès
2019-11-06 18:30                       ` pelzflorian (Florian Pelz)
2019-11-07 20:24                         ` Ludovic Courtès
2019-11-06 14:49                   ` Ludovic Courtès
2019-11-06 18:21                     ` pelzflorian (Florian Pelz)
2020-07-26 17:52 ` Vagrant Cascadian
2020-07-27 11:20   ` pelzflorian (Florian Pelz)
2020-07-28  9:44 ` bug#26302: Fwd: website translation English (US)? pelzflorian (Florian Pelz)
2020-07-28 10:03   ` zimoun
2020-07-28 16:02   ` pelzflorian (Florian Pelz)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://guix.gnu.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200729192103.2fug7t6to2tuiwew@pelzflorian.localdomain \
    --to=pelzflorian@pelzflorian.de \
    --cc=26302@debbugs.gnu.org \
    --cc=danielaluraa@gmail.com \
    --cc=ludo@gnu.org \
    --cc=sirgazil@zoho.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).