Re: Translating the Emacs manuals (a summary)

[Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>]

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