Translating the Emacs manuals (a summary) - revision

From d4d7ae6897e6e3d6f09f8e197078d6d7a3c9e37a Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <[email protected]>
Date: Sat, 20 Jan 2024 23:19:14 +0900
Subject: [PATCH] New doc/lang/readme file for translators

---
 doc/lang/readme | 194 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 194 insertions(+)
 create mode 100644 doc/lang/readme

diff --git a/doc/lang/readme b/doc/lang/readme
new file mode 100644
index 00000000000..b77af32d926
--- /dev/null
+++ b/doc/lang/readme
@@ -0,0 +1,194 @@
+# Translating the Emacs manuals
+
+## Copyright assignment
+
+People who contribute translated documents should provide a copyright
+assignment to the Free Software Foundation. See the 'Copyright
+Assignment' section in the Emacs manual.
+
+
+## Translated documents licence
+
+The translated documents are distributed under the same licence as the
+original documents: the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation.
+
+See https://www.gnu.org/licenses/fdl-1.3.html for more information.
+
+
+## Location
+
+### texinfo source files
+
+Translated manuals source files are located in the `doc/lang`
+directory, under the directory whose name corresponds to the
+translated language.
+
+  For ex. French manuals sources are found under `doc/lang/fr`.
+
+The structure of the language folders should match the structure of
+the English manuals (i.e. include `misc`, `man`, `lispref`,
+`lispintro`, `emacs`).
+
+### built files
+
+Translated deliverables in info format are built at release time and
+are made available for local installation.
+
+
+## Format
+
+The manuals and their translations are written in the texinfo format
+(with the exception of the org-mode manual that is written in org-mode
+and of illustrations for the Introduction to Emacs Lisp Programming
+that are written in eps).
+
+See https://www.gnu.org/software/texinfo/ for more information.
+
+You should install the texinfo utilities to be able to verify the
+translated files, and refer to the texinfo manual if you do not
+understand the meaning of the various texinfo declarations.
+
+Emacs has a texinfo mode that properly highlights the texinfo code to
+make it easier to see which parts are text to be translated and which
+parts are not.
+
+
+### Texinfo specific issues
+
+Until the Emacs/Texinfo projects provide better solutions, here are a
+few rules to follow:
+
+- Under each `@node`, add an `@anchor` that has the same content at
+the original English `@node`.
+
+- Translate the `@node` content but leave the `@anchor` in English.
+
+- Most Emacs manuals are set to include the `docstyle.texi` file. This
+file adds the `@documentencoding UTF-8` directive to the targeted
+manual. There is no need to add this directive in a manual that
+includes `docstyle.texi`.
+
+- Add a `@documentlanguage` directive that includes your language.
+
+  For ex. `@documentlanguage zh`
+
+This directive has currently little effect but will be useful in the
+future.
+
+- The `@author` directive can be used for the translator's name.
+
+  For ex. `@author traduit en français par Achile Talon`
+
+
+## Fixing the original document
+
+During the course of the translation, you will find parts of the
+original document that need to be updated or otherwise fixed. If you
+do not intend to modify the original document right away, do not add
+notes to it but rather keep such notes inside your translation as TODO
+items until you action them.
+
+
+## Sending contributions
+
+Send your contributions (either files or revisions) to the emacs-devel
+list for review.
+
+Always send contributions in the format of the original document. Most
+of the contents in the Emacs manuals are in texinfo format, so do not
+send contributions that are in derivative formats (e.g. info, html,
+docbook, plain text, etc.)
+
+Before sending files for review, ensure that they have been properly
+checked for spelling/grammar/typography by at least using the tools
+that Emacs provides.
+
+You should also make sure that the texinfo files build properly on
+your system.
+
+Send your contributions as patches (`git diff -p --stat`), and prefer
+the `git format-patch` form because the format allows easier review
+and easier installation of the changes by someone with write access to
+the repository.
+
+The Emacs project has a lot of coding, documentation and commenting
+conventions. Sending such patches allows the project managers to make
+sure that the contributions comply with the various conventions.
+
+
+## Discussing translation issues
+
+Translation-related discussions are welcome on the emacs-devel
+list. Discussions specific to your language do not have to take place
+in English.
+
+
+## Translation teams
+
+The number of words in the Emacs manuals is above 2,000,000 words and
+growing. While one individual could theoretically translate all the
+files, it is more practical to work in language teams.
+
+If you have a small group of translators willing to help, make sure
+that the files are properly reviewed before sending them to
+emacs-devel (see above).
+
+
+## Translation processes
+
+Emacs does not yet provide tools that significantly help the
+translation process. A few useful functions would be
+
+- automatic lookup of a list of glossary items when starting to work
+on a translation “unit” (paragraph or otherwise), such glossary
+terms should be easily insertable at point,
+
+- automatic lookup of past translations to check for similarity and
+improve homogeneity over the whole document set, such past
+translation matches should be easily insertable at point,
+
+etc.
+
+
+### Using the PO format as an intermediate translation format
+
+Although the PO format has not been developed with documentation in
+mind, it is well known among free software translation teams and you
+can easily use the `po4a` utility to convert texinfo to PO for work in
+translation tools that support the PO format.
+
+See https://po4a.org for more information.
+
+However, regardless of the intermediate file format that you might
+use, you should only send texinfo files for review to emacs-devel.
+
+
+### Free tools that you can use in your processes
+
+A number of free software tools exist, outside the Emacs ecosystem, to
+help translators (amateurs and professionals alike) with the
+translation process.
+
+If you find that Emacs should implement some of their features, you
+are welcome to provide patches to the Emacs project.
+
+Such tools include:
+
+- the GNOME Translation Editor, https://wiki.gnome.org/Apps/Gtranslator/
+- KDE's Lokalize, https://apps.kde.org/lokalize/
+- OmegaT, http://omegat.org
+- the Okapi Framework, https://www.okapiframework.org
+- pootle, https://pootle.translatehouse.org
+
+etc.
+
+
+# Licence of this document
+
+Copyright (C) 2024 Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without any warranty.
-- 
2.43.0