From patchwork Tue Apr 13 22:48:57 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Julien Lepiller X-Patchwork-Id: 28486 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 3CE3327BC75; Tue, 13 Apr 2021 23:50:12 +0100 (BST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_MSPIKE_H4,RCVD_IN_MSPIKE_WL,SPF_HELO_PASS, T_DKIM_INVALID,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.2 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 4A59E27BC74 for ; Tue, 13 Apr 2021 23:50:11 +0100 (BST) Received: from localhost ([::1]:60888 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lWRrG-00080h-BZ for patchwork@mira.cbaines.net; Tue, 13 Apr 2021 18:50:10 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:42382) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lWRr8-00080N-9w for guix-patches@gnu.org; Tue, 13 Apr 2021 18:50:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:49584) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lWRr8-0001Oh-1l for guix-patches@gnu.org; Tue, 13 Apr 2021 18:50:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lWRr7-0008GL-Vf for guix-patches@gnu.org; Tue, 13 Apr 2021 18:50:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#47763] [PATCH] doc: Document translation process. Resent-From: Julien Lepiller Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 13 Apr 2021 22:50:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 47763 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 47763@debbugs.gnu.org X-Debbugs-Original-To: guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.161835416731709 (code B ref -1); Tue, 13 Apr 2021 22:50:01 +0000 Received: (at submit) by debbugs.gnu.org; 13 Apr 2021 22:49:27 +0000 Received: from localhost ([127.0.0.1]:32893 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lWRqT-0008FB-He for submit@debbugs.gnu.org; Tue, 13 Apr 2021 18:49:27 -0400 Received: from lists.gnu.org ([209.51.188.17]:34258) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lWRqQ-0008F2-Ve for submit@debbugs.gnu.org; Tue, 13 Apr 2021 18:49:19 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:42354) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lWRqQ-0007rI-NW for guix-patches@gnu.org; Tue, 13 Apr 2021 18:49:18 -0400 Received: from lepiller.eu ([2a00:5884:8208::1]:51598) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lWRqN-00011m-3o for guix-patches@gnu.org; Tue, 13 Apr 2021 18:49:18 -0400 Received: from lepiller.eu (localhost [127.0.0.1]) by lepiller.eu (OpenSMTPD) with ESMTP id 83347f61 for ; Tue, 13 Apr 2021 22:49:08 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=lepiller.eu; h=date:from :to:subject:message-id:mime-version:content-type; s=dkim; bh=kAW cOwnaSNARc/rWeoYX/24Ly2oo1jqPy72JRx4H97U=; b=ZjXm+/0nTqOxlsTA+os +DGxgDZldWOJvIGeJBc6+3aAgsUioMkhp0V/VtqhU0JzfAD6Aw07r03yIrE5NPtz xDcZU/T7sm7/eSbDpENFG+YgfroBNjp4DOIevkzEFfvfJ4ii6nie5QA5AB5WNV8x qbX7+fF4kUiHLSrUqBCYQ0k5s81n1zAsCUotQGsAD1hjiJ/ZyJ08XcEB4drRuseD Mit/CNXyOiNIjfl7zWPkvg2PN+Htd+H9dPEKqJTvhIfWm/zhhmMwi9qf3ucy3h6/ 46nkB2wXkQ2NwOsiMWGWKDYGPzmcAT8lR5VRP8LQX3OofkMD6afM1SkR3uKB3dfK P7w== Received: by lepiller.eu (OpenSMTPD) with ESMTPSA id d2474d95 (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256:NO) for ; Tue, 13 Apr 2021 22:49:08 +0000 (UTC) Date: Wed, 14 Apr 2021 00:48:57 +0200 From: Julien Lepiller Message-ID: <20210414004857.2c560714@tachikoma.lepiller.eu> X-Mailer: Claws Mail 3.17.8 (GTK+ 2.24.32; x86_64-pc-linux-gnu) MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:5884:8208::1; envelope-from=julien@lepiller.eu; helo=lepiller.eu X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" X-getmail-retrieved-from-mailbox: Patches Hi Guix! The attached patch adds a new section to the manual (and therefore should wait for the next release since we are in string freeze) that documents the translation process for contributors. From ce110d021935467753e0086c6992c45bf9a48388 Mon Sep 17 00:00:00 2001 From: Julien Lepiller Date: Wed, 14 Apr 2021 00:16:01 +0200 Subject: [PATCH] doc: Document translation process. doc/contributing.texi (Translating Guix): New section. doc/guix.texi (Top): Add a reference to the new section. --- doc/contributing.texi | 205 ++++++++++++++++++++++++++++++++++++++++++ doc/guix.texi | 2 +- 2 files changed, 206 insertions(+), 1 deletion(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 9a09de93e6..8c697dc122 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -29,6 +29,7 @@ choice. * Tracking Bugs and Patches:: Using Debbugs. * Commit Access:: Pushing to the official repository. * Updating the Guix Package:: Updating the Guix package definition. +* Translating Guix:: Make Guix speak your native language. @end menu @node Building from Git @@ -1429,3 +1430,207 @@ This check can be disabled, @emph{at your own peril}, by setting the @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When this variable is set, the updated package source is also added to the store. This is used as part of the release process of Guix. + +@cindex translation +@cindex l10n +@cindex i18n +@cindex native language support +@node Translating Guix +@section Translating Guix + +Writing code and packages is not the only way to provide a meaningful +contribution to Guix. Translating to a language you speak is another +example of a valuable contribution you can make. This section is designed +to describe the translation process. It gives you advice on how you can +get involved, what can be translated, what mistakes you should avoid and +what we can do to help you! + +Guix is a big project that has multiple components that can be translated. +We coordinate the translation effort on a +@uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance} +hosted by our friends at Fedora. You will need an account to submit +translations. + +Some of the software packaged in Guix also contain translations. We do not +host a translation platform for them. If you want to translate a package +provided by Guix, you should contact their developpers or find the information +on their website. As an example, you can find the homepage of the +@code{hello} package by typing @code{guix show hello}. On the ``homepage'' +line, you will see @url{https://www.gnu.org/software/hello/} as the homepage. + +Many GNU and non-GNU packages can be translated on the +@uref{https://translationproject.org,Translation Project}. Some projects +with multiple components have their own platform. For instance, GNOME has +its own platform, @uref{https://l10n.gnome.org/,Damned Lies}. + +Guix has five components hosted on Weblate. + +@itemize +@item @code{guix} contains all the strings from the Guix software (the + guided system installer, the package manager, etc), excluding packages. +@item @code{packages} contains the synopsis (single-sentence description + of packages) and description (longer description) of packages in Guix. +@item @code{website} contains the official Guix website, except for + blog posts and multimedia content. +@item @code{documentation-manual} corresponds to this manual. +@item @code{documentation-cookbook} is the component for the cookbook. +@end itemize + +@subsubheading General Directions + +Once you get an account, you should be able to select a component from +@uref{https://translate.fedoraproject.org/projects/guix/,the guix project}, +and select a language. If your language does not appear in the list, go +to the bottom and click on the ``Start new translation'' button. Select +the language you want to translate to from the list start the translation. + +Like lots of other free software packages, Guix uses +@uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations, +with which translatable strings are extracted from the source code to so-called +PO files. + +Even though PO files are text files, changes should not be made with a text +editor but with PO editing software. Weblate integrates PO editing +functionality. Alternatively, translators can use any of various +free-software tools for filling in translations, of which +@uref{https://poedit.net/,Poedit} is one example, and (after logging in) +@uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed +file. There is also a special +@uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU +Emacs. Over time translators find out what software they are happy with and +what features they need. + +On Weblate, you will find various links to the editor, that will show various +subsets (or all) of the strings. Have a look around and at the +@uref{https://docs.weblate.org/en/latest/,documentation} to familiarize +yourself with the platform. + +@subsubheading Translation Components + +In this section, we provide more detailed guidance on the translation +process, as well as details on what you should or should not do. When in +doubt, please contact us, we will be happy to help! + +@table @asis +@item guix +Guix is written in the Guile programming language, and some strings contain +special formating that is interpreted by Guile. These special formating +should be highlighted by Weblate. They start with @code{~} followed by one +or more characters. + +When printing the string, Guile replaces the special formating symbols with +actual values. For instance, the string @samp{ambiguous package specification +`~a'} would be substituted to contain said package specification instead of +@code{~a}. To properly translate this string, you must keep the formating +code in your translation, although you can place it where it makes sense in +your language. For instance, the French translation says @samp{spécification +du paquet « ~a » ambiguë} because the adjective needs to be placed in the +end of the sentence. + +If there are multiple formating symbols, make sure to respect the order. +Guile does not know in which order you intended the string to be read, so it +will substitute the symbols in the same order as the English sentence. + +As an example, you cannot translate @samp{package '~a' has been superseded by +'~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would be +reversed. If foo1 is superseeded by foo2, the translation would read +@samp{'foo1' superseeds package 'foo2'}. To work around this problem, it +is possible to use more advanced formating to select a given piece of data, +instead of following the default English order. + +@item packages + +Package descriptions occasionally contain texinfo markup. Texinfo markup +looks like @samp{@@code@{rm -rf@}}, @samp{@@emph@{important@}}, etc. When +translating, please leave markup as is. + +The characters after ``@@'' form the name of the markup, and the text between +``@{'' and ``@}'' is its content. In general, you should not translate the +content of markup like @code{@@code}, as it contains literal code that do not +change with language. You can translate the content of formating markup such +as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do +not translate the name of the markup, or it will not be recognized. + +@item documentation-manual and documentation-cookbook + +The manual and the cookbook both use texinfo. As for @code{packages}, please +keep texinfo markup as is. There are more possible markup types in the manual +than in the package descriptions. In general, do not translate the content +of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You +should translate the content of formating markup. + +The manual contains sections that can be refered to by name by @code{@@ref}, +@code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do +not have to translate their content. If you keep the English title, we will +automatically replace it with your translation of that title. This ensures +that texinfo will always be able to find the node. If you decide to change +the translation of the title, the references will automatically be updated +and you will not have to update them all yourself. + +@item website + +The website pages are written using SXML, an s-expression version of HTML, +the basic language of the web. We have a process to extract translatable +strings from the source, and replace complex s-expressions with a more familiar +XML markup, where each markup is numbered. Translators can arbitrarily change +the ordering, as in the following example. + +@example +#. 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.2>Defining-Packages.html as native <2>Guile modules." +msgstr "Pakete werden als reine <2>Guile-Module <1>definiert<1.1>de<1.2>Pakete-definieren.html." +@end example + +Note that you need to include the same markups. You cannot skip any. +@end table + +In case you make a mistake, the component might fail to build properly with your +language, or even make guix pull fail. To prevent that, we have a process +in place to check the content of the files before pushing to our repository. +We will not be able to update the translation for your language in Guix, so +we will notify you (through weblate and/or by email) so you get a chance to +fix the issue. + +@subsubheading Outside of Weblate + +Currently, some parts of Guix cannot be translated on Weblate, help wanted! + +@itemize +@item Guix pull news can be translated in @file{news.scm}, but is not + available from Weblate. If you want to provide a translation, you + can prepare a patch as described above, or simply send us your + translation with the name of the news entry your translate and your + language. +@item Guix blog posts cannot currently be translated. +@item The installer script is entirely in English. +@item Some of the libraries Guix cannot be translated or are translated outside + of the Guix project. Guile itself does not provide a translation + mechanism. +@item Other manuals linked from this manual might not be translated. +@end itemize + +@subsubheading Translation Infrastructure + +Weblate is backed by a git repository from which it discovers new strings to +translate and pushes new and updated translations. Normally, it would be +enough to give it commit access to our repositories. However, we decided +to use a separate repository for two reasons. First, we would have to give +Weblate commit access and authorize its signing key, but we do not trust it +in the same way we trust guix developpers, especially since we do not manage +the instance ourselves. Second, if translators mess something up, it can +break the generation of the website and/or guix pull for all our users, +independently of their language. + +For these reasons, we use a dedicated repository to host translations, and we +synchronize it with our guix and artworks repositories after checking no issue +was introduced in the translation. + +Developpers can download the latest PO files from weblate in the Guix +repository by runnig the @command{make download-po} target. It will +automatically download the latest files from weblate, reformat them to a +canonical form, and check they do not contain issues. + +The manual needs to be built again to check for additional issues that might +crash texinfo. diff --git a/doc/guix.texi b/doc/guix.texi index fa14b35e2a..63e5adae07 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -146,7 +146,7 @@ Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you would like to translate it in your native language, consider joining @uref{https://translate.fedoraproject.org/projects/guix/documentation-manual, -Weblate}. +Weblate} (@pxref{Translating Guix}). @menu * Introduction:: What is Guix about? -- 2.31.1