Emacs manuals translation readme

Emacs manuals translation readme

[Jean-Christophe Helary]

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

I think I have covered all the recent comments to the original proposal.

1. the "lang" directory is renamed "translations"

→ the length of the name is not really relevant since we have term 
  completions in Emacs
→ "translations" is more indicative of the contents of the folder than 
  "lang"

2. the readme includes more references to the GNU project translation 
projects without suggesting that Emacs manual translations should be 
included in the projects.


Let me know if there are other issues.




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

From 28bf850f11bb91fdc957141d37ffa14d2df95c02 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


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

From 2c5b054215bbfbc79591130ddd5d30ca440d439f 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 | 203 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 203 insertions(+)
 create mode 100644 doc/translations/readme

diff --git a/doc/translations/readme b/doc/translations/readme
new file mode 100644
index 00000000000..36a86b58e11
--- /dev/null
+++ b/doc/translations/readme
@@ -0,0 +1,203 @@
+# 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.
-- 
2.43.0

Re: Emacs manuals translation readme

[Jean-Christophe Helary]

I gathered all the comments and integrated them, so I think that the 
patches are now ready for a formal review and eventual installation.

Are there things that I have overlooked?

> On Jan 26, 2024, at 10:04, Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org> wrote:
> 
> I think I have covered all the recent comments to the original proposal.
> 
> 1. the "lang" directory is renamed "translations"
> 
> → the length of the name is not really relevant since we have term 
>  completions in Emacs
> → "translations" is more indicative of the contents of the folder than 
>  "lang"
> 
> 2. the readme includes more references to the GNU project translation 
> projects without suggesting that Emacs manual translations should be 
> included in the projects.
> 
> 
> Let me know if there are other issues.
> 
> <0001-Rename-doc-lang-to-doc-translations.patch>
> 
> <0002-New-doc-translations-readme-file-for-translators.patch>

Re: Emacs manuals translation readme

[Po Lu]

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

> I gathered all the comments and integrated them, so I think that the 
> patches are now ready for a formal review and eventual installation.
>
> Are there things that I have overlooked?
>
>> On Jan 26, 2024, at 10:04, Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org> wrote:
>> 
>> I think I have covered all the recent comments to the original proposal.
>> 
>> 1. the "lang" directory is renamed "translations"
>> 
>> → the length of the name is not really relevant since we have term 
>>  completions in Emacs
>> → "translations" is more indicative of the contents of the folder than 
>>  "lang"

`translations' doesn't conform to the 8.3 naming scheme used under
MS-DOS, and we only require a long file name driver for building Emacs,
not for running it, and certainly not for reading Info manuals.  But I
could well be mistaken.

Re: Emacs manuals translation readme

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel <emacs-devel@gnu.org>
> Date: Tue, 13 Feb 2024 10:31:26 +0800
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
> >> I think I have covered all the recent comments to the original proposal.
> >> 
> >> 1. the "lang" directory is renamed "translations"
> >> 
> >> → the length of the name is not really relevant since we have term 
> >>  completions in Emacs
> >> → "translations" is more indicative of the contents of the folder than 
> >>  "lang"
> 
> `translations' doesn't conform to the 8.3 naming scheme used under
> MS-DOS, and we only require a long file name driver for building Emacs,
> not for running it, and certainly not for reading Info manuals.  But I
> could well be mistaken.

Long file names will only be a problem if they cash with other file
names in the same directory.  In this case I don't think there will be
such a clash.

FWIW, I prefer 'lang', for more than one reason.  But I won't fight if
others prefer 'translations'.

Re: Emacs manuals translation readme

[Jean-Christophe Helary]

> On Feb 13, 2024, at 12:32, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Po Lu <luangruo@yahoo.com>
>> Cc: emacs-devel <emacs-devel@gnu.org>
>> Date: Tue, 13 Feb 2024 10:31:26 +0800
>> 
>> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> writes:
>> 
>>>> I think I have covered all the recent comments to the original proposal.
>>>> 
>>>> 1. the "lang" directory is renamed "translations"
>>>> 
>>>> → the length of the name is not really relevant since we have term
>>>> completions in Emacs
>>>> → "translations" is more indicative of the contents of the folder than
>>>> "lang"
>> 
>> `translations' doesn't conform to the 8.3 naming scheme used under
>> MS-DOS, and we only require a long file name driver for building Emacs,
>> not for running it, and certainly not for reading Info manuals.  But I
>> could well be mistaken.
> 
> Long file names will only be a problem if they cash with other file
> names in the same directory.  In this case I don't think there will be
> such a clash.
> 
> FWIW, I prefer 'lang', for more than one reason.  But I won't fight if
> others prefer 'translations'.

I prefer “translations” because the folder is clearly intended to 
receive translated documents and will only be (actively) used by 
translation teams.

But I think that’s something Stefan and you should discuss, since he is 
the one who made the proposal.

Re: Emacs manuals translation readme

[Po Lu]

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

> I prefer “translations” because the folder is clearly intended to 
> receive translated documents and will only be (actively) used by 
> translation teams.

`lang' is no less clear, since the relation between a manual and a
folder by that name most users will perceive is that the one holds
localized (translated) versions of the other.

Re: Emacs manuals translation readme

[Eli Zaretskii]

> Date: Tue, 13 Feb 2024 02:25:32 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> 
> I gathered all the comments and integrated them, so I think that the 
> patches are now ready for a formal review and eventual installation.
> 
> Are there things that I have overlooked?

Thanks.  I was about to install those changes, but then I saw a few
minor nits that still needed attention:

> From 28bf850f11bb91fdc957141d37ffa14d2df95c02 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

When I wrote doc/LANG/, I meant doc/fr/, doc/de/, etc.  I didn't mean
a literal "LANG" string.  So the above renaming now has an extra
subdirectory, which was not something I had in mind.  Stefan Kangas
agreed with my proposal back then.  So do you object to have manuals
translated to French in doc/fr/, rather than in doc/translations/fr/ ?
If you do not object, please modify the patch accordingly.

>  doc/translations/readme | 203 ++++++++++++++++++++++++++++++++++++++++

Please make that README, in all-upper case.  That is how we name all
the readme files in the tree.

> +People who contribute translated documents should provide a copyright
> +assignment to the Free Software Foundation. See the 'Copyright
> +Assignment' section in the Emacs manual.  ^^

We use the US English convention of leaving 2 spaces between
sentences (here and everywhere else in the patch).

> +The translated documents are distributed under the same licence as the
                                                           ^^^^^^^
Please use the US English spelling: "license".

> +### texinfo source files
> +
> +Translated manuals source files are located in the `doc/translations`
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is better to say "The source files of the translated manuals...",
as the use of so-called "construct state" for more than 2 words is
problematic in English, and produces potentially confusing text.

> +directory, under the directory whose name corresponds to the
> +translated language.
> +
> +  For ex. French manuals sources are found under

Please use "Fore example" or "E.g.", not the short form.

> +  `doc/translations/fr`.

If you agree to place them under doc/fr, the above needs to be
adjusted.  Also, please quote 'like this', not `like this`.

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

Likewise here (and elsewhere: we don't use the Markdown style of
quoting in our text documents.

> +You should install the texinfo utilities to be able to verify the

"Texinfo", capitalized (here and elsewhere in the patch).

> +Send your contributions (either files or revisions) to the emacs-devel
> +list for review.

Please use emacs-devel@gnu.org, to make the address complete.

> +- automatic lookup of a list of glossary items when starting to work
> +on a translation “unit” (paragraph or otherwise), such glossary
                    ^^^^^^
It is better not to use non-ASCII characters, to make sure any
terminal can display the README file.  Here, I suggest "units", with
ASCII double quotes.

Please post a fixed patch, and I will install it.

Thanks.

Re: Emacs manuals translation readme

[Jean-Christophe Helary]

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

Thank you, Eli.

Here are the patches. And comments inline.




> On Feb 17, 2024, at 17:55, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> When I wrote doc/LANG/, I meant doc/fr/, doc/de/, etc.  I didn't mean
> a literal "LANG" string.  So the above renaming now has an extra
> subdirectory, which was not something I had in mind.  Stefan Kangas
> agreed with my proposal back then.  So do you object to have manuals
> translated to French in doc/fr/, rather than in doc/translations/fr/ ?

I think that’s weird.

We’ll end up having something like 

de
emacs
fr
ja
lispintro
lispref
man
misc
zh

which is very confusing. I’ve never seen that. I’d understand if the 
existing English manuals were moved under doc/en, but since that’s not 
the case, I’m not sure I understand the rationale. Still, if you and 
Stefan are ok with that, I won’t object.

> If you do not object, please modify the patch accordingly.
> 
>> doc/translations/readme | 203 ++++++++++++++++++++++++++++++++++++++++
> 
> Please make that README, in all-upper case.  That is how we name all
> the readme files in the tree.

Done.

>> +People who contribute translated documents should provide a copyright
>> +assignment to the Free Software Foundation. See the 'Copyright
>> +Assignment' section in the Emacs manual.  ^^
> 
> We use the US English convention of leaving 2 spaces between
> sentences (here and everywhere else in the patch).

Done.

>> +The translated documents are distributed under the same licence as the
>                                                           ^^^^^^^
> Please use the US English spelling: "license".

Done.

>> +### texinfo source files
>> +
>> +Translated manuals source files are located in the `doc/translations`
>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> It is better to say "The source files of the translated manuals...",
> as the use of so-called "construct state" for more than 2 words is
> problematic in English, and produces potentially confusing text.

Thank you. Done.

>> +directory, under the directory whose name corresponds to the
>> +translated language.
>> +
>> +  For ex. French manuals sources are found under
> 
> Please use "Fore example" or "E.g.", not the short form.

Done.

>> +  `doc/translations/fr`.
> 
> If you agree to place them under doc/fr, the above needs to be
> adjusted.  Also, please quote 'like this', not `like this`.

Done.

>> +The structure of the language folders should match the structure of
>> +the English manuals (i.e. include `misc`, `man`, `lispref`,
>> +`lispintro`, `emacs`).
> 
> Likewise here (and elsewhere: we don't use the Markdown style of
> quoting in our text documents.

Ok. Done. I also replaced the header marks (#, ##) with org marks (*, 
**)

>> +You should install the texinfo utilities to be able to verify the
> 
> "Texinfo", capitalized (here and elsewhere in the patch).

Done.

>> +Send your contributions (either files or revisions) to the emacs-devel
>> +list for review.
> 
> Please use emacs-devel@gnu.org, to make the address complete.

Done.

>> +- automatic lookup of a list of glossary items when starting to work
>> +on a translation “unit” (paragraph or otherwise), such glossary
>                    ^^^^^^
> It is better not to use non-ASCII characters, to make sure any
> terminal can display the README file.  Here, I suggest "units", with
> ASCII double quotes.
> 
> Please post a fixed patch, and I will install it.

I just added a sentence that was last suggested by Richard in a private 
exchange regarding questions about how to comply with the GFDL, in the 
second section.

[-- Attachment #2: 0002-Translation-README-file.patch --]
[-- Type: application/octet-stream, Size: 7569 bytes --]

From c6cc4321f81fda7feeefbdd7cfb14ba037876dbb Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
Date: Sun, 18 Feb 2024 00:04:18 +0900
Subject: [PATCH 2/2] Translation README file

---
 doc/README | 204 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 doc/README

diff --git a/doc/README b/doc/README
new file mode 100644
index 00000000000..61d9d362527
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,204 @@
+* 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 license
+
+The translated documents are distributed under the same license 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.
+
+If you have questions regarding the use of the FDL license in your
+translation work that are not answered in the FAQ, do not hesitate to
+contact the GNU project: https://www.gnu.org/contact/
+
+** Location
+
+*** Texinfo source files
+
+The source files of the translated manuals are located in the doc/
+directory, under the directory whose name corresponds to the translated
+language.
+
+  E.g. French manuals sources are found under doc/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.
+
+  E.g. @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.
+
+  E.g. @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
+emacs-devel@gnu.org 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.
-- 
2.43.0


[-- Attachment #3: 0001-move-translations-to-the-doc-root.patch --]
[-- Type: application/octet-stream, Size: 562 bytes --]

From e4656496b588c721bce83f9deca98547838c8100 Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
Date: Sun, 18 Feb 2024 00:02:09 +0900
Subject: [PATCH 1/2] move translations to the doc/ root

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

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

Re: Emacs manuals translation readme

[Stefan Kangas]

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

>> On Feb 17, 2024, at 17:55, Eli Zaretskii <eliz@gnu.org> wrote:
>>
>> When I wrote doc/LANG/, I meant doc/fr/, doc/de/, etc.  I didn't mean
>> a literal "LANG" string.  So the above renaming now has an extra
>> subdirectory, which was not something I had in mind.  Stefan Kangas
>> agreed with my proposal back then.  So do you object to have manuals
>> translated to French in doc/fr/, rather than in doc/translations/fr/ ?
>
> I think that’s weird.
>
> We’ll end up having something like
>
> de
> emacs
> fr
> ja
> lispintro
> lispref
> man
> misc
> zh
>
> which is very confusing. I’ve never seen that. I’d understand if the
> existing English manuals were moved under doc/en, but since that’s not
> the case, I’m not sure I understand the rationale. Still, if you and
> Stefan are ok with that, I won’t object.

I agree that it seems rather unusual.  I thought we were discussing

    doc/translations/fr

rather than

    doc/fr/

otherwise what is the point of the "translations" directory?

Re: Emacs manuals translation readme

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 17 Feb 2024 13:18:24 -0500
> Cc: emacs-devel@gnu.org
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
> >> On Feb 17, 2024, at 17:55, Eli Zaretskii <eliz@gnu.org> wrote:
> >>
> >> When I wrote doc/LANG/, I meant doc/fr/, doc/de/, etc.  I didn't mean
> >> a literal "LANG" string.  So the above renaming now has an extra
> >> subdirectory, which was not something I had in mind.  Stefan Kangas
> >> agreed with my proposal back then.  So do you object to have manuals
> >> translated to French in doc/fr/, rather than in doc/translations/fr/ ?
> >
> > I think that’s weird.
> >
> > We’ll end up having something like
> >
> > de
> > emacs
> > fr
> > ja
> > lispintro
> > lispref
> > man
> > misc
> > zh
> >
> > which is very confusing. I’ve never seen that. I’d understand if the
> > existing English manuals were moved under doc/en, but since that’s not
> > the case, I’m not sure I understand the rationale. Still, if you and
> > Stefan are ok with that, I won’t object.
> 
> I agree that it seems rather unusual.  I thought we were discussing
> 
>     doc/translations/fr
> 
> rather than
> 
>     doc/fr/

No, we weren't.  You agreed to the doc/fr/ suggestion.

But anyway, I won't fight if you two prefer doc/translations/fr.  I
just wanted to set the record straight.

Re: Emacs manuals translation readme

[Eli Zaretskii]

> Date: Sat, 17 Feb 2024 15:07:05 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: emacs-devel@gnu.org
> 
> Thank you, Eli.
> 
> Here are the patches. And comments inline.

Thanks, installed on master.

I thought you and Stefan preferred to have the files in
doc/translations/?  So I moved the files there, and also fixed a few
minor issues I found in README.

So now this stuff is in its place and ready for adding more
translations.  What is still missing is the Make wizardry to produce
the translated manuals as part of the build and install then as part
of "make install".  Patches welcome.  When this is done, we should
call out the translations in NEWS.

Re: Emacs manuals translation readme

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I agree that it seems rather unusual.  I thought we were discussing
>>
>>     doc/translations/fr
>>
>> rather than
>>
>>     doc/fr/
>
> No, we weren't.  You agreed to the doc/fr/ suggestion.

I had to look at the archives, and I think I see where the confusion is
coming from.

I agreed to this:

 . Texinfo sources go into the doc/LANG/ subdirectory, under which
   there should be the same subdirectories 'emacs', 'lispref', misc'
   etc. (we will actually create a directory when the first
   translation of the corresponding English manual will be
   submitted);

For some reason, I didn't understand that LANG was a placeholder for
"de|fr|sv" (which seems obvious now) rather than "lang|translations".

> But anyway, I won't fight if you two prefer doc/translations/fr.  I
> just wanted to set the record straight.

Thanks.

Re: Emacs manuals translation readme

[Jean-Christophe Helary]

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



> On Feb 18, 2024, at 17:00, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Sat, 17 Feb 2024 15:07:05 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: emacs-devel@gnu.org
>> 
>> Thank you, Eli.
>> 
>> Here are the patches. And comments inline.
> 
> Thanks, installed on master.

Eli,

I did not think you'd install the file right away and had sent to 
document to a professional proofreader I work with to polish the 
wording.

This patch includes her modifications and a few small things I had 
added in between.

Would you mind considering the propositions?


> I thought you and Stefan preferred to have the files in
> doc/translations/?  So I moved the files there, and also fixed a few
> minor issues I found in README.

Thank you. It looks like a misunderstanding on our parts.

> So now this stuff is in its place and ready for adding more
> translations.  What is still missing is the Make wizardry to produce
> the translated manuals as part of the build and install then as part
> of "make install".  Patches welcome.  When this is done, we should
> call out the translations in NEWS.

I'll need more time to understand the build process but I'll do my best 
to provide a patch, unless somebody does that before me...

Jean-Christophe


[-- Attachment #2: 0001-proofreading-of-translations-README.patch --]
[-- Type: application/octet-stream, Size: 10700 bytes --]

From d0b1ad8babeef25f44035d23f8fc76681f7d61f0 Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
Date: Mon, 19 Feb 2024 20:05:14 +0900
Subject: [PATCH] proofreading of translations/README

---
 doc/translations/README | 135 ++++++++++++++++++++--------------------
 1 file changed, 67 insertions(+), 68 deletions(-)

diff --git a/doc/translations/README b/doc/translations/README
index c689f0b14b3..35b9b9e9cf9 100644
--- a/doc/translations/README
+++ b/doc/translations/README
@@ -15,22 +15,23 @@ any later version published by the Free Software Foundation.
 
 See https://www.gnu.org/licenses/fdl-1.3.html for more information.
 
-If you have questions regarding the use of the FDL license in your
-translation work that are not answered in the FAQ, do not hesitate to
-contact the GNU project: https://www.gnu.org/contact/
+If you have any questions regarding the use of the FDL license in your
+translation work that do not appear in the FAQ, feel free to contact the
+GNU project.
 
-** Location
+See https://www.gnu.org/contact/ for more information.
+
+** Location of the translated files
 
 *** Texinfo source files
 
-The source files of the translated manuals are located in the doc/
-directory, under the directory whose name corresponds to the translated
-language.
+The source files of the translated manuals are located in the
+doc/translations directory, under the translated language sub-directory.
 
-  E.g., French manuals sources are found under doc/fr.
+  E.g., French manual 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).
+The structure of each language folder should match that of the English
+manuals (i.e. include misc, man, lispref, lispintro, emacs).
 
 *** built files
 
@@ -38,22 +39,21 @@ Translated deliverables in info format are built at release time and are
 made available for local installation.
 
 
-** Format
+** Source files 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).
+(with the exception of the org-mode manual, which is written in
+org-mode, and illustrations for the Introduction to Emacs Lisp
+Programming, which 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.
+You must install the Texinfo utilities in order to verify the translated
+files, and refer to the Texinfo manual for information on 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.
+Emacs has a Texinfo mode that highlights the parts of the Texinfo code
+to be translated for easy reference.
 
 
 *** Texinfo specific issues
@@ -61,21 +61,21 @@ parts are not.
 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.
+- Under each @node, add an @anchor that has the same content as 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.
+  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.
 
   E.g., @documentlanguage zh
 
-This directive has currently little effect but will be useful in the
+This directive currently has little effect but will be useful in the
 future.
 
 - The @author directive can be used for the translator's name.
@@ -85,34 +85,35 @@ future.
 
 ** 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.
+During the course of the translation, you might encounter passages in
+the original document that need to be updated or otherwise corrected, or
+even run into a bug in Emacs.  If you cannot immediately correct the
+problem, please file a bug report promptly.
 
 See the 'Bugs' section in the Emacs manual.
 
-** Sending contributions
+** Sending your contributions
 
-Send your contributions (either files or revisions) to
-emacs-devel@gnu.org for review.
+Send your contributions (files or revisions) for review to the Emacs
+development list at emacs-devel@gnu.org. Subscribing to the list is not
+obligatory.
 
 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.)
+of the content in the Emacs manuals is in Texinfo format, so please do
+not send contributions 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.
+Before sending files for review, please ensure that they have been
+thoroughly checked for spelling/grammar/typography by at least using the
+tools provided by Emacs.
 
-You should also make sure that the Texinfo files build properly on your
+Please 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.
+git format-patch form, since the format allows for easier review and
+easier installation of the changes by the persons 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
@@ -121,25 +122,24 @@ 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
+Translation-related discussions are welcome on the emacs development
+list. Discussions specific to your language do not have to be in
 English.
 
 
 ** Translation teams
 
-The number of words in the Emacs manuals is above 2,000,000 words and
+The number of words in the Emacs manuals is over 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).
+If you have a small group of translators willing to help, please make
+sure that the files are properly reviewed before sending them to the
+Emacs development list (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.
+Please refer to the translation-related documents maintained by the GNU
+Project, and contact your language translation team to learn the
+practices they have developed over the years.
 
 See https://www.gnu.org/server/standards/README.translations.html for
 more information.
@@ -148,46 +148,45 @@ more information.
 ** Translation processes
 
 Emacs does not yet provide tools that significantly help the translation
-process.  A few useful functions would be
+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,
+  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.
+  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
+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.
+you should only send files in the original format (Texinfo, org-mode,
+eps) for review and installation.
 
 
 *** 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.
+A number of free software tools are available outside the Emacs
+ecosystem, to help translators (both amateur and professional) in the
+translation process.
 
-If you find that Emacs should implement some of their features, you are
+If they have any features that you think Emacs should implement, 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
+- OmegaT, https://omegat.org
 - the Okapi Framework, https://www.okapiframework.org
 - pootle, https://pootle.translatehouse.org
 
-- 
2.43.0

Re: Emacs manuals translation readme

[Eli Zaretskii]

> Date: Mon, 19 Feb 2024 11:13:01 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: emacs-devel@gnu.org
> 
> > On Feb 18, 2024, at 17:00, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> Date: Sat, 17 Feb 2024 15:07:05 +0000
> >> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> >> Cc: emacs-devel@gnu.org
> >> 
> >> Thank you, Eli.
> >> 
> >> Here are the patches. And comments inline.
> > 
> > Thanks, installed on master.
> 
> Eli,
> 
> I did not think you'd install the file right away

I couldn't know that, given that you didn't update the patch for quite
some time, and then asked whether anything else needed to be done.  I
took that last message as meaning that you would like this to be
installed.  So I did.  Apologies if I misunderstood, but generally
this is what pinging about a patch means around here.

> and had sent to document to a professional proofreader I work with
> to polish the wording.
> 
> This patch includes her modifications and a few small things I had 
> added in between.
> 
> Would you mind considering the propositions?

Thanks, I installed the changes, and then made a few minor changes of
my own.

Re: Emacs manuals translation readme

[Jean-Christophe Helary]

> On Feb 19, 2024, at 22:22, Eli Zaretskii <eliz@gnu.org> wrote:
>> I did not think you'd install the file right away
> 
> I couldn't know that, given that you didn't update the patch for quite
> some time, and then asked whether anything else needed to be done.  I
> took that last message as meaning that you would like this to be
> installed.  So I did.  Apologies if I misunderstood, but generally
> this is what pinging about a patch means around here.

Sorry. I'll be more careful.

>> and had sent to document to a professional proofreader I work with
>> to polish the wording.
>> 
>> This patch includes her modifications and a few small things I had
>> added in between.
>> 
>> Would you mind considering the propositions?
> 
> Thanks, I installed the changes, and then made a few minor changes of
> my own.

Thank you.