all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Emacs manuals translation readme
@ 2024-01-26  1:04 Jean-Christophe Helary
  2024-02-13  2:25 ` Jean-Christophe Helary
  0 siblings, 1 reply; 15+ messages in thread
From: Jean-Christophe Helary @ 2024-01-26  1:04 UTC (permalink / raw)
  To: emacs-devel

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


^ permalink raw reply related	[flat|nested] 15+ messages in thread
end of thread, other threads:[~2024-02-19 14:20 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-01-26  1:04 Emacs manuals translation readme Jean-Christophe Helary
2024-02-13  2:25 ` Jean-Christophe Helary
2024-02-13  2:31   ` Po Lu
2024-02-13  3:32     ` Eli Zaretskii
2024-02-13  3:51       ` Jean-Christophe Helary
2024-02-13  4:02         ` Po Lu
2024-02-17  8:55   ` Eli Zaretskii
2024-02-17 15:07     ` Jean-Christophe Helary
2024-02-17 18:18       ` Stefan Kangas
2024-02-17 18:30         ` Eli Zaretskii
2024-02-18 10:45           ` Stefan Kangas
2024-02-18  8:00       ` Eli Zaretskii
2024-02-19 11:13         ` Jean-Christophe Helary
2024-02-19 13:22           ` Eli Zaretskii
2024-02-19 14:20             ` Jean-Christophe Helary

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.