From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id IOhiHCQgdmDpFQEAgWs5BA (envelope-from ) for ; Wed, 14 Apr 2021 00:50:12 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id 4A09FiQgdmDjNQAAB5/wlQ (envelope-from ) for ; Tue, 13 Apr 2021 22:50:12 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id E0BBF1BA4A for ; Wed, 14 Apr 2021 00:50:11 +0200 (CEST) Received: from localhost ([::1]:60888 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lWRrG-00080h-W4 for larch@yhetil.org; Tue, 13 Apr 2021 18:50:11 -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 Content-Type: multipart/mixed; boundary="MP_/=mHSfqQgs4Ln1kbk/M0BhAX" 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+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1618354212; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:resent-cc:resent-from:resent-sender: resent-message-id:list-id:list-help:list-unsubscribe:list-subscribe: list-post:dkim-signature; bh=GpVF5nSz81ISsqzJ54hSDTFjcZwT6PnnSCp0j3RL12g=; b=cs/6RqwrbkpehsIaFDcthqYrD+fRT/i3RARyQAxd/HQhCXskH/nLaa2mwPedWAbFlaxEoA oykErgw7alSIQKxzn8n2eLDJ0z/E3a14z9a/xVxkeBnjfdao+zqxL4Q4IrhQJUbP6zJSmY NS80catUfLd1A/T2KOYv0RJ9VMWIlmFgFLqb9mEh0nu0JsD2VI7do0vPuN1K8nxn9S5PQ+ NTHR25jq5mIL+GwziiLOKFCgVRMyt26dbOHqe/W3nFbnqUPcl5/S8Yf2n4ArLTpoG99hpG 2G2pMxp7sNjtPFW4PaYpcq4s886hWhbPVqdeW7nBzbjC6zREWwCkmO+KPRCRPg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1618354212; a=rsa-sha256; cv=none; b=VVFhcv+6vcS2j5VkEn9UCVap6hHkLaRg2K9rMo+AX14khVC7A2RlFXFM0ni7R7V72OXmyI H6pD1Nkoq26UyHrXhbopQFowuiInigex1vcKrTIOUvt+WFZrmEWk+How6lXmeCxuM1P5up DiIGeWroowf6QwVx0EZvf8ufXUwKYsvyPio82XKNiVvt31h7KF1cn3pqo0yZasmbSot5jq 8N0oUpRxqexela/WdaZvBypIWjuYH7Z29CZrKTdlz1Gvf1x95zrQS4ZyS81GgUW3EWIvhk gCkvfi8ohNOItlEkyk0d5iCWDmCjPNu46Sp2HK/LhnOoyhupu9yAJHbfRpwXew== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=lepiller.eu header.s=dkim header.b="ZjXm+/0n"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=lepiller.eu (policy=none); spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Spam-Score: 0.97 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=lepiller.eu header.s=dkim header.b="ZjXm+/0n"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=lepiller.eu (policy=none); spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Queue-Id: E0BBF1BA4A X-Spam-Score: 0.97 X-Migadu-Scanner: scn0.migadu.com X-TUID: CmC8OVUNJkhk --MP_/=mHSfqQgs4Ln1kbk/M0BhAX Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Content-Disposition: inline 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. --MP_/=mHSfqQgs4Ln1kbk/M0BhAX Content-Type: text/x-patch Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename=0001-doc-Document-translation-process.patch =46rom 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 =20 @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 informa= tion +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 homepa= ge. + +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 packag= es. +@item @code{packages} contains the synopsis (single-sentence description + of packages) and description (longer description) of packages in Gui= x. +@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 translatio= ns, +with which translatable strings are extracted from the source code to so-c= alled +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 chang= ed +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 a= nd +what features they need. + +On Weblate, you will find various links to the editor, that will show vari= ous +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 specifica= tion +`~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=C3=A9ci= fication +du paquet =C2=AB ~a =C2=BB ambigu=C3=AB} 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 betw= een +``@{'' 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 s= uch +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}, ple= ase +keep texinfo markup as is. There are more possible markup types in the ma= nual +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 wi= ll +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 fam= iliar +XML markup, where each markup is numbered. Translators can arbitrarily ch= ange +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 wit= h 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 repositor= y. +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 ou= tside + 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 mana= ge +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 i= ssue +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 mig= ht +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, =D0=A0=D1=83=D0=BA=D0=BE=D0=B2=D0=BE=D0=B4= =D1=81=D1=82=D0=B2=D0=BE GNU Guix}). If you would like to translate it in your native language, consider joining @uref{https://translate.fedoraproject.org/projects/guix/documentation-manu= al, -Weblate}. +Weblate} (@pxref{Translating Guix}). =20 @menu * Introduction:: What is Guix about? --=20 2.31.1 --MP_/=mHSfqQgs4Ln1kbk/M0BhAX--