Translating the Emacs manuals (a summary)

Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

I’m trying here to make a summary of the discussions that we’ve had so far, in the hope of being able to propose a proper readme file at some point in the close future.

I hope I've not forgotten anything.

JC

---
# Translating the Emacs manuals

## Location

Translated manuals sources are located in the ’doc/lang’ directory, under the directory whose name corresponds to the translated language.

For ex. French manual sources are found under ’doc/lang/fr’.

The structure of the language folders should match the structure of the English manuals (i.e. ’misc’, ’man’, ’lispref’, ’lispintro’, ’emacs’).


## Format

The translated manuals should be in the same format as the English sources: TexInfo.


### TexInfo specific issues

Until Emacs/TexInfo provide better solutions, here are a few rules to follow:

- ’@node’ items should be translated but should be accompanied by an ’@anchor’ that contains the original English ’@node’ contents.

- ’@documentencoding UTF-8’ is automatically included in the file since it is in ’doc/emacs/docstyle.texi’. Do not add it to your file headers.

- You should add a ’@documentlanguage’ directive that includes your language.

For ex. ’@documentlanguage zh’

- ’@author’ can be used for the translator’s name.

Fr ex. `@author traduit en français par Achile Talon`


## Committing the files

Like other source files, translations should be committed to a separate branch for revision. Ideally, the branch name should be suggestive of what they contain.

For ex: ’origin/translations/emacs-lisp-intro-ar.texi’

Before committing the files for revision, 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.

Once the files are committed, announce the commit to the emacs-devel list so that fellow translators can check the file and review it.

## Discussions about 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.


## Notes about the original document

During the course of the translation, you will find parts of the original document that needs to be updated or otherwise fixed. If you do not intend to modify the original documents right away, do not add notes to the original documents but rather keep such notes inside your translation as TODO items until you action them.


## Translation teams

The number of words in the Emacs manuals is above 2,000,000 words. 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 committing them (see above.)


## Translation processes

Emacs does not provide yet tools that significantly help the translation process. A few ideal 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

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.

Re: Translating the Emacs manuals (a summary)

[Eli Zaretskii]

> Date: Fri, 19 Jan 2024 18:00:34 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: help-texinfo@gnu.org
> 
> I’m trying here to make a summary of the discussions that we’ve had so far, in the hope of being able to propose a proper readme file at some point in the close future.
> 
> I hope I've not forgotten anything.

Looks fine to me, thanks.

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

> On Jan 20, 2024, at 4:54, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Fri, 19 Jan 2024 18:00:34 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: help-texinfo@gnu.org
>> 
>> I’m trying here to make a summary of the discussions that we’ve had so far, in the hope of being able to propose a proper readme file at some point in the close future.
>> 
>> I hope I've not forgotten anything.
> 
> Looks fine to me, thanks.

(I am making amendments at the moment and that triggers a few extra questions.)

What about people who do not have commit rights to the repository?
Can they send a file to the list and ask for it to be committed to a review branch?

Re: Translating the Emacs manuals (a summary)

[Eli Zaretskii]

> Date: Sat, 20 Jan 2024 04:37:05 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: emacs-devel@gnu.org
> 
> > On Jan 20, 2024, at 4:54, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> Date: Fri, 19 Jan 2024 18:00:34 +0000
> >> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> >> Cc: help-texinfo@gnu.org
> >> 
> >> I’m trying here to make a summary of the discussions that we’ve had so far, in the hope of being able to propose a proper readme file at some point in the close future.
> >> 
> >> I hope I've not forgotten anything.
> > 
> > Looks fine to me, thanks.
> 
> (I am making amendments at the moment and that triggers a few extra questions.)
> 
> What about people who do not have commit rights to the repository?
> Can they send a file to the list and ask for it to be committed to a review branch?

They can send a file or they can send a patch, yes.  Patches are
preferable, especially if they are in "git format-patch" form, because
they allow easier review and easier installation of the changes by
someone with write access.

Also, if we are talking about such fine details, let's not forget that
changes should be always posted for review, no matter if the author
does or doesn't have write access to the repository.  This is
especially important in this case, since many contributors are likely
to be unaware of our coding, documentation, and commenting
conventions, and so patch review is an important part of making sure
the results comply to our conventions.

Re: Translating the Emacs manuals (a summary)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The GNU Project has set up a translation team for each language,
though not all languages ever translated currently have active teams.
The team works together to make translations correct.

I suggest it would be a good idea to put manual translators
in touch with the language's translation team.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Translating the Emacs manuals (a summary) - revision

[Jean-Christophe Helary]

[-- Attachment #1: Type: text/plain, Size: 390 bytes --]

Here is the revised, and hopefully useable version of the document.

I've added a section on copyright assignment, on the GFDL, on external 
free tools, and modified a few things here and there.

Is the markdown format OK for such a readme file, or do we prefer 
something else like no decorations at all?


And I tried to use git format-patch too. Let me know how that worked.


[-- Attachment #2: 0001-New-doc-lang-readme-file-for-translators.patch --]
[-- Type: application/octet-stream, Size: 7141 bytes --]

From d4d7ae6897e6e3d6f09f8e197078d6d7a3c9e37a Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
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

Re: Translating the Emacs manuals (a summary) - revision

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

> From d4d7ae6897e6e3d6f09f8e197078d6d7a3c9e37a Mon Sep 17 00:00:00 2001
> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Sat, 20 Jan 2024 23:19:14 +0900
> Subject: [PATCH] New doc/lang/readme file for translators
>
> ---
>  doc/lang/readme | 194 ++++++++++++++++++++++++++++++++++++++++++++++++

Your text LGTM.

I again propose renaming this subdirectory to

    doc/translations

The name "lang" is competing for the letter "l" with "lispintro" and
"lispref" which not only makes the directory listing harder to read but
also makes completion harder.  It is also not self-explanatory in the
same way that "translations" is.

Re: Translating the Emacs manuals (a summary) - revision

[Jean-Christophe Helary]

[-- Attachment #1: Type: text/plain, Size: 639 bytes --]



> On Jan 21, 2024, at 8:00, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
>> From d4d7ae6897e6e3d6f09f8e197078d6d7a3c9e37a Mon Sep 17 00:00:00 2001
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Sat, 20 Jan 2024 23:19:14 +0900
>> Subject: [PATCH] New doc/lang/readme file for translators
>> 
>> ---
>> doc/lang/readme | 194 ++++++++++++++++++++++++++++++++++++++++++++++++
> 
> Your text LGTM.
> 
> I again propose renaming this subdirectory to
> 
>    doc/translations

Et voilà !



[-- Attachment #2: 0002-New-doc-translations-readme-file-for-translators.patch --]
[-- Type: application/octet-stream, Size: 7204 bytes --]

From 51e77acae61f52c8759cca8e2a8ebf097f52c6f4 Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
Date: Sun, 21 Jan 2024 11:05:57 +0900
Subject: [PATCH 2/2] New doc/translations/readme file for translators

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

diff --git a/doc/translations/readme b/doc/translations/readme
new file mode 100644
index 00000000000..0fc68c564de
--- /dev/null
+++ b/doc/translations/readme
@@ -0,0 +1,195 @@
+# 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/translations`
+directory, under the directory whose name corresponds to the
+translated language.
+
+  For ex. French manuals sources are found under
+  `doc/translations/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


[-- Attachment #3: 0001-Rename-doc-lang-to-doc-translations.patch --]
[-- Type: application/octet-stream, Size: 613 bytes --]

From 84061196faffee9ee9fc4aedf23920b4dc126102 Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
Date: Sun, 21 Jan 2024 11:04:09 +0900
Subject: [PATCH 1/2] Rename doc/lang to doc/translations

---
 doc/{lang => translations}/fr/misc/ses-fr.texi | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename doc/{lang => translations}/fr/misc/ses-fr.texi (100%)

diff --git a/doc/lang/fr/misc/ses-fr.texi b/doc/translations/fr/misc/ses-fr.texi
similarity index 100%
rename from doc/lang/fr/misc/ses-fr.texi
rename to doc/translations/fr/misc/ses-fr.texi
-- 
2.43.0

Re: Translating the Emacs manuals (a summary) - revision

[Juri Linkov]

>>  doc/lang/readme | 194 ++++++++++++++++++++++++++++++++++++++++++++++++
>
> I again propose renaming this subdirectory to
>
>     doc/translations
>
> The name "lang" is competing for the letter "l" with "lispintro" and
> "lispref" which not only makes the directory listing harder to read but
> also makes completion harder.  It is also not self-explanatory in the
> same way that "translations" is.

Isn't "translations" overly long?  Usually such long names
cause inconveniences to users, albeit minor.  This is why
the word "internationalization" is shortened to just "i18n".
Would it be possible to use "i18n" here?

Re: Translating the Emacs manuals (a summary) - revision

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

>>>  doc/lang/readme | 194 ++++++++++++++++++++++++++++++++++++++++++++++++
>>
>> I again propose renaming this subdirectory to
>>
>>     doc/translations
>>
>> The name "lang" is competing for the letter "l" with "lispintro" and
>> "lispref" which not only makes the directory listing harder to read but
>> also makes completion harder.  It is also not self-explanatory in the
>> same way that "translations" is.
>
> Isn't "translations" overly long?  Usually such long names
> cause inconveniences to users, albeit minor.  This is why
> the word "internationalization" is shortened to just "i18n".
> Would it be possible to use "i18n" here?

I don't know, but shouldn't completion mean that it's anyways just
"doc/t TAB"?

Re: Translating the Emacs manuals (a summary) - revision

[Jean-Christophe Helary]

> On Jan 22, 2024, at 5:01, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Juri Linkov <juri@linkov.net> writes:
> 
>>>> doc/lang/readme | 194 ++++++++++++++++++++++++++++++++++++++++++++++++
>>> 
>>> I again propose renaming this subdirectory to
>>> 
>>>    doc/translations
>>> 
>>> The name "lang" is competing for the letter "l" with "lispintro" and
>>> "lispref" which not only makes the directory listing harder to read but
>>> also makes completion harder.  It is also not self-explanatory in the
>>> same way that "translations" is.
>> 
>> Isn't "translations" overly long?  Usually such long names
>> cause inconveniences to users, albeit minor.  This is why
>> the word "internationalization" is shortened to just "i18n".
>> Would it be possible to use "i18n" here?

Internationalization does not mean translation. Internationalization is 
the process by which a software can be adapted to support various 
locales and languages.

Here, the more appropriate term would be localization, but again, it's 
a process.

Having a doc/translations folder allows us to work on Emacs 
localization.

https://en.wikipedia.org/wiki/Internationalization_and_localization

And the practical context in which the word will be used is a git 
checkout/commit, so, as Stefan puts it here:

> I don't know, but shouldn't completion mean that it's anyways just
> "doc/t TAB"?

So there is really no inconvenience at all here.

Translation is sometimes abbreviated t9n, but it's weird, and 
translators do not generally use that term.

Re: Translating the Emacs manuals (a summary)

[Matthias Meulien]

[-- Attachment #1: Type: text/plain, Size: 183 bytes --]

Gasp! With Achille Talon as contributor to the French translation we're
going to expand the number of words by a huge factor... Is Git LFS enabled
on the remote repository?

Matthias

[-- Attachment #2: Type: text/html, Size: 289 bytes --]

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

> On Jan 20, 2024, at 5:36, Matthias Meulien <orontee@gmail.com> wrote:
> 
> Gasp! With Achille Talon as contributor to the French translation we're going to expand the number of words by a huge factor... Is Git LFS enabled on the remote repository?

:)

Re: Translating the Emacs manuals (a summary)

[Patrice Dumas]

Not necessarily very important, but UTF-8 is the default input encoding
since Texinfo 6.7 (23 September 2019), depending on the Texinfo minimal
version you target, you could remove the "@documentencoding UTF-8",
and/or change the wording of the recommendation.

On Fri, Jan 19, 2024 at 06:00:34PM +0000, Jean-Christophe Helary wrote:
> - ’@documentencoding UTF-8’ is automatically included in the file since it is in ’doc/emacs/docstyle.texi’. Do not add it to your file headers.


-- 
Pat

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

> On Jan 21, 2024, at 3:01, Patrice Dumas <pertusus@free.fr> wrote:
> 
> Not necessarily very important, but UTF-8 is the default input encoding
> since Texinfo 6.7 (23 September 2019), depending on the Texinfo minimal
> version you target, you could remove the "@documentencoding UTF-8",
> and/or change the wording of the recommendation.
> 
> On Fri, Jan 19, 2024 at 06:00:34PM +0000, Jean-Christophe Helary wrote:
>> - ’@documentencoding UTF-8’ is automatically included in the file since it is in ’doc/emacs/docstyle.texi’. Do not add it to your file headers.

Do you mean that all the manuals that include this directive predate 
Texinfo 6.7 (very likely) and that basically we could remove the 
directive from all the manuals without changing anything (considering 
that they'd be built with texinfo 6.7+)?

Re: Translating the Emacs manuals (a summary)

[Patrice Dumas]

On Sat, Jan 20, 2024 at 06:08:07PM +0000, Jean-Christophe Helary wrote:
> > On Jan 21, 2024, at 3:01, Patrice Dumas <pertusus@free.fr> wrote:
> > 
> > Not necessarily very important, but UTF-8 is the default input encoding
> > since Texinfo 6.7 (23 September 2019), depending on the Texinfo minimal
> > version you target, you could remove the "@documentencoding UTF-8",
> > and/or change the wording of the recommendation.
> > 
> > On Fri, Jan 19, 2024 at 06:00:34PM +0000, Jean-Christophe Helary wrote:
> >> - ’@documentencoding UTF-8’ is automatically included in the file since it is in ’doc/emacs/docstyle.texi’. Do not add it to your file headers.
> 
> Do you mean that all the manuals that include this directive predate 
> Texinfo 6.7 (very likely)

Not necessarily, this is needed if processed by older versions.

>  and that basically we could remove the 
> directive from all the manuals without changing anything (considering 
> that they'd be built with texinfo 6.7+)?

Yes.

-- 
Pat

Re: Translating the Emacs manuals (a summary)

[Eli Zaretskii]

> Date: Sat, 20 Jan 2024 19:01:25 +0100
> From: Patrice Dumas <pertusus@free.fr>
> Cc: emacs-devel@gnu.org, help-texinfo@gnu.org
> 
> Not necessarily very important, but UTF-8 is the default input encoding
> since Texinfo 6.7 (23 September 2019), depending on the Texinfo minimal
> version you target, you could remove the "@documentencoding UTF-8",
> and/or change the wording of the recommendation.

Emacs still supports very old Texinfo versions, so we keep
@documentencoding for those.

Re: Translating the Emacs manuals (a summary)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

These notes seem basically good, but I think an item should be added
to address the issue of following the GNU Free Documentation License.

There are two points I suggest changing.

  > During the course of the translation, you will find parts of the
  > original document that needs to be updated or otherwise fixed. If
  > you do not intend to modify the original documents right away, do
  > not add notes to the original documents but rather keep such notes
  > inside your translation as TODO items until you action them.

That is not what we want to recommend.  Keeping a private note about a
problem you spotted does not lead to fixing it soon.

Instead, please advise translators, "Uf you find a problem in a file
in the Emacs distribution, including in a manual, please file a bug
report promply so someone can fix it soon."

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

Please suggest that people look at the subdirectories of www.gnu.org,
for instance www.gnu.org/philosophy, to see the way the translators of
the web site use PO to help them do it.  The master version of each
page is in English and does not have PO markup; however, the
translators maintain a PO-annotated version of each page.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

> On Jan 22, 2024, at 12:33, Richard Stallman <rms@gnu.org> wrote:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
> These notes seem basically good, but I think an item should be added
> to address the issue of following the GNU Free Documentation License.

The revision I sent as a patch yesterday includes this:

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

Is that sufficient?

> There are two points I suggest changing.
> 
>> During the course of the translation, you will find parts of the
>> original document that needs to be updated or otherwise fixed. If
>> you do not intend to modify the original documents right away, do
>> not add notes to the original documents but rather keep such notes
>> inside your translation as TODO items until you action them.
> 
> That is not what we want to recommend.  Keeping a private note about a
> problem you spotted does not lead to fixing it soon.
> 
> Instead, please advise translators, "Uf you find a problem in a file
> in the Emacs distribution, including in a manual, please file a bug
> report promply so someone can fix it soon."

I changed the item to this:

---
## Fixing the original document

During the course of the translation, you might find parts of the
original document that need to be updated or otherwise fixed, or even
bugs in Emacs. If you do not intend to provide fixes right away,
please file a bug report promptly so someone can fix it soon.

See the 'Bugs' section in the Emacs manual.
---

Is that what you had in mind?

>> 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.
> 
> Please suggest that people look at the subdirectories of www.gnu.org,
> for instance www.gnu.org/philosophy, to see the way the translators of
> the web site use PO to help them do it.  The master version of each
> page is in English and does not have PO markup; however, the
> translators maintain a PO-annotated version of each page.

To also answer your:

> I suggest it would be a good idea to put manual translators
> in touch with the language's translation team.


I modified the Translation teams section this way:

---
## 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).

Although the Emacs manuals translation is not yet formally integrated
with the rest of the GNU Project translation project, you are invited
to refer to the translation-related documents that the GNU Project
maintains and to get in touch with your language's translation team.

See https://www.gnu.org/server/standards/README.translations.html for
more information.
---

Is it satisfactory?

I'll send a new patch when I have your green light.

Re: Translating the Emacs manuals (a summary)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

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

  > Is that sufficient?

In the abstract, yes.  But it is good to refer to practical guidance
for what this means.  I don't know whether we have any yet, but
we should.

  > ---
  > ## Fixing the original document

  > During the course of the translation, you might find parts of the
  > original document that need to be updated or otherwise fixed, or even
  > bugs in Emacs. If you do not intend to provide fixes right away,
  > please file a bug report promptly so someone can fix it soon.

  > See the 'Bugs' section in the Emacs manual.
  > ---

  > Is that what you had in mind?

Yes.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

>> ## 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.
>> ---
> 
>> Is that sufficient?
> 
> In the abstract, yes.  But it is good to refer to practical guidance
> for what this means.  I don't know whether we have any yet, but
> we should.

I guess that practical guidance could be referred to from that link 
when it exists since the document includes various pointers about the 
FDL. In the meanwhile, let me keep the text as it is.

Re: Translating the Emacs manuals (a summary)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Although the Emacs manuals translation is not yet formally integrated
  > with the rest of the GNU Project translation project,

I am not sure there is a need to "integrate" the two activities, or
that we ought to suggest that.  My idea is more basic: it would be
wise for manual translators to talk with the www.gnu.org translators
and learn from the practices they have developed over the years.
There's no need for the activities' practices to be identical, let
alone combined.

  > you are invited
  > to refer to the translation-related documents that the GNU Project
  > maintains and to get in touch with your language's translation team.

Yes, that is the point.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

>> Although the Emacs manuals translation is not yet formally integrated
>> with the rest of the GNU Project translation project,
> 
> I am not sure there is a need to "integrate" the two activities, or
> that we ought to suggest that.  My idea is more basic: it would be
> wise for manual translators to talk with the www.gnu.org translators
> and learn from the practices they have developed over the years.
> There's no need for the activities' practices to be identical, let
> alone combined.
> 
>> you are invited
>> to refer to the translation-related documents that the GNU Project
>> maintains and to get in touch with your language's translation team.
> 
> Yes, that is the point.

Ok, I changed the paragraph to:


## 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).

You are invited to refer to the translation-related documents that the
GNU Project maintains and to get in touch with your language's
translation team to learn from the practices they have developed over
the years.

See https://www.gnu.org/server/standards/README.translations.html for
more information.

Re: Translating the Emacs manuals (a summary)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

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

That is not specific, so it won't be helpful.
What constiutues proper review?

Is that stated earlier in the document?  (I can't find the whole document.)
If so, maybe there is no problem.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

[-- Attachment #1: Type: text/plain, Size: 660 bytes --]

>> 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).
> 
> That is not specific, so it won't be helpful.
> What constiutues proper review?
> 
> Is that stated earlier in the document?  (I can't find the whole document.)
> If so, maybe there is no problem.

The document has been sent as a patch.

Here it is, in plain text form.

There is an earlier paragraph that has:

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


[-- Attachment #2: readme --]
[-- Type: application/octet-stream, Size: 6718 bytes --]

# 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/translations`
directory, under the directory whose name corresponds to the
translated language.

  For ex. French manuals sources are found under
  `doc/translations/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 might find parts of the
original document that need to be updated or otherwise fixed, or even
bugs in Emacs. If you do not intend to provide fixes right away,
please file a bug report promptly so someone can fix it soon.

See the 'Bugs' section in the Emacs manual.

## 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).

You are invited to refer to the translation-related documents that the
GNU Project maintains and to get in touch with your language's
translation team to learn from the practices they have developed over
the years.

See https://www.gnu.org/server/standards/README.translations.html for
more information.


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

Re: Translating the Emacs manuals (a summary)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Please forgive my delay.

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

  > Is that sufficient?

It is sufficienr in a rigid logical sense, but not sufficient to be
helpful.  For the final version, we will publish it the same way as we
publish original manuals.  The translators don't have any
responsibilities about that except to sign the assignment.

But we should tell people how to handle parts of translations,
patches, and translations we have not yet approved.

Don't worry about it for now -- we will do it when needed,


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

>> ## 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.
>> ---
> 
>> Is that sufficient?
> 
> It is sufficienr in a rigid logical sense, but not sufficient to be
> helpful.

:) I understand.

> For the final version, we will publish it the same way as we
> publish original manuals.  The translators don't have any
> responsibilities about that except to sign the assignment.

Ok. That's noted in the readme already.

> But we should tell people how to handle parts of translations,
> patches, and translations we have not yet approved.
> 
> Don't worry about it for now -- we will do it when needed,

Ok. Thank you.

Re: Translating the Emacs manuals (a summary)

[Ralph Lin]

[-- Attachment #1: Type: text/plain, Size: 1863 bytes --]


I'm actually working on my own Emacs manu translation. Can can sign my translated files under my own copyright(using the same fdl1.3)?

________________________________
发件人: help-texinfo-bounces+ralphlin24=hotmail.com@gnu.org <help-texinfo-bounces+ralphlin24=hotmail.com@gnu.org> 代表 Richard Stallman <rms@gnu.org>
发送时间: 2024年2月13日 10:15
收件人: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
抄送: emacs-devel@gnu.org <emacs-devel@gnu.org>; help-texinfo@gnu.org <help-texinfo@gnu.org>
主题: Re: Translating the Emacs manuals (a summary)

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Please forgive my delay.

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

  > Is that sufficient?

It is sufficienr in a rigid logical sense, but not sufficient to be
helpful.  For the final version, we will publish it the same way as we
publish original manuals.  The translators don't have any
responsibilities about that except to sign the assignment.

But we should tell people how to handle parts of translations,
patches, and translations we have not yet approved.

Don't worry about it for now -- we will do it when needed,


--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)




[-- Attachment #2: Type: text/html, Size: 3260 bytes --]