* [PATCH v2 1/2] docs: doc-guide: add a guide for translators
2026-10-15 12:56 [PATCH v2 0/2] docs: add a guide for translators Daniel Pereira
@ 2026-10-15 12:56 ` Daniel Pereira
2026-10-15 12:56 ` [PATCH v2 2/2] docs: pt_BR: translate doc-guide/translations.rst Daniel Pereira
1 sibling, 0 replies; 3+ messages in thread
From: Daniel Pereira @ 2026-10-15 12:56 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Shuah Khan, Randy Dunlap, Alex Shi, Yanteng Si, Dongliang Mu,
Chen-Yu Yeh, Weijie Yuan, Federico Vaga, Akira Yokosawa,
Carlos Bilbao, Avadhut Naik, linux-doc, linux-kernel
The documentation has seven translations, but nothing in the English
documentation explains how to contribute to them. The only guide that
exists, Documentation/translations/zh_CN/how-to.rst, is written in
Chinese and covers the zh_CN translation only.
As a result, the same problems come up over and over in the review of
translation patches: labels and citations copied from the original,
which are global in Sphinx and collide with the English ones; partial
builds with SPHINXDIRS that hide those collisions; lines over 80
columns; translations not added to any toctree; missing commit
descriptions, tags separated by blank lines, HTML email rejected by the
lists, and the documentation maintainer left out of the recipients.
Add Documentation/doc-guide/translations.rst, a guide that covers the
whole workflow of a translation: choosing what to translate, the layout
of a translated document (path, header, labels, citations,
cross-references, what must not be translated), translation quality and
terminology, adding the document to the build, checking it with a full
htmldocs build, checkpatch and checktransupdate.py, preparing and
sending the patch, the review process, keeping translations up to date
and starting a new translation. The commit message format it suggests
is the one already recognized by tools/docs/checktransupdate.py.
Link the guide from the doc-guide index and from the translations
index.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
Changes in v2:
- Drop the Assisted-by references from the AI tools section, the tags
example and the checklist (Weijie Yuan).
- Use a plain path in the ":Original:" example and drop ":Translator:"
from it (Weijie Yuan).
v1: https://lore.kernel.org/linux-doc/20261013003702.5824-2-danielmaraboo@gmail.com/
Documentation/doc-guide/index.rst | 1 +
Documentation/doc-guide/translations.rst | 694 +++++++++++++++++++++++
Documentation/translations/index.rst | 3 +
3 files changed, 698 insertions(+)
create mode 100644 Documentation/doc-guide/translations.rst
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index f078baddf..0016aed59 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -12,4 +12,5 @@ How to write kernel documentation
parse-headers
contributing
maintainer-profile
+ translations
checktransupdate
diff --git a/Documentation/doc-guide/translations.rst b/Documentation/doc-guide/translations.rst
new file mode 100644
index 000000000..9f7e0496a
--- /dev/null
+++ b/Documentation/doc-guide/translations.rst
@@ -0,0 +1,694 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Translating the kernel documentation
+====================================
+
+The kernel documentation is written in English, and English is the only
+official version of it. Translations exist to make that documentation
+accessible to people who are more comfortable reading in another
+language; they live under ``Documentation/translations/``, with one
+directory per language.
+
+This document explains how to contribute to those translations: how to
+pick something to translate, how a translated document is laid out, how
+to check your work, how to send it, what to expect from the review, and
+how to keep a translation current once it has been merged. It also
+covers what is needed to start a translation into a new language.
+
+It does not replace the general documents on how to contribute to the
+kernel; a translation patch is a kernel patch, and everything described
+in Documentation/process/submitting-patches.rst applies to it. What
+follows focuses on the details that are specific to translations and on
+the mistakes that most often cause translation patches to be sent back.
+
+Some translations have additional, language-specific guidance written in
+their own language; for example, the Simplified Chinese team maintains
+Documentation/translations/zh_CN/how-to.rst. Where such a guide exists,
+read it as well.
+
+
+Principles
+==========
+
+Before starting, read the disclaimer in
+:ref:`Documentation/translations/index.rst <translations_disclaimer>`.
+Its main points shape everything else in this document:
+
+- **English is authoritative.** When a translation and the English
+ original disagree, the English version is correct.
+
+- **A translation is not a fork.** It must not add, remove or change
+ information. If you find an error, an omission or an outdated
+ statement in the original, fix the English document first, with a
+ separate patch sent to the documentation maintainers. Once that change
+ is merged, the translation can follow it.
+
+- **Translation maintainers only accept translation work**: new
+ translations, updates that follow changes in the original, and fixes
+ to existing translations.
+
+- **Adapting is allowed; changing the meaning is not.** Every language
+ has its own grammar and idioms, and a literal word-for-word rendering
+ is often wrong. Rephrase as much as your language needs, as long as
+ the reader ends up with the same information as a reader of the
+ original.
+
+
+Before you start
+================
+
+Find the translation team
+-------------------------
+
+Each translation is listed in the MAINTAINERS file with a ``F:`` line
+pointing to its directory. You can find the people responsible for a
+translation with::
+
+ $ scripts/get_maintainer.pl -f Documentation/translations/<lang>/
+
+Look at recent discussions on the linux-doc mailing list
+(https://lore.kernel.org/linux-doc/) to get a feel for how the team works,
+which conventions it follows and what reviewers usually ask for. If you
+are unsure about something, ask on the list before investing a lot of
+work; translation maintainers are generally happy to help newcomers.
+
+Choose what to translate
+------------------------
+
+Good candidates are documents that many people read: the development
+process documents under ``Documentation/process/``, the admin guide,
+and the guides for writing documentation. Long, rapidly changing or very
+specialized documents are harder to keep current and are better left for
+later.
+
+Check that the document is not already translated, and that nobody else
+is working on it:
+
+- look in ``Documentation/translations/<lang>/``;
+
+- search the linux-doc archive on lore.kernel.org for the file name; a
+ pending patch, or a recent review, means someone is already on it;
+
+- use ``tools/docs/checktransupdate.py`` to list the documents that have
+ no translation yet::
+
+ $ tools/docs/checktransupdate.py -l <lang> --print-missing-translations
+
+ See Documentation/doc-guide/checktransupdate.rst for the details.
+
+Avoid having several people translate files in the same directory at the
+same time. The patches then tend to touch the same ``index.rst`` and end
+up conflicting with each other. If you plan to translate a whole
+directory, say so on the list.
+
+If you are new to kernel development, start with a short document. The
+first patch is where most of the process problems show up, and they are
+much easier to fix on a 60-line file than on a 2000-line one.
+
+Set up your environment
+-----------------------
+
+Translations are merged through the documentation tree, so base your
+work on its ``docs-next`` branch (the ``T:`` line of the DOCUMENTATION
+entry in MAINTAINERS gives its location)::
+
+ $ git remote add docs git://git.lwn.net/linux.git
+ $ git fetch docs
+ $ git switch -c my-translation docs/docs-next
+
+Some translations are collected in their own tree first; if the
+MAINTAINERS entry for your language has its own ``T:`` line, ask the
+translation maintainers which branch to use.
+
+You will need a working Sphinx installation to build the documentation.
+``tools/docs/sphinx-pre-install`` checks your system and tells you what is
+missing; Documentation/doc-guide/sphinx.rst has the details.
+
+You will also need to be able to send plain-text email with
+``git send-email`` or a mail client configured as described in
+Documentation/process/email-clients.rst. The vger.kernel.org mailing
+lists reject HTML email, so replies sent from a web mail interface in its
+default configuration never reach the list.
+
+
+Anatomy of a translated document
+================================
+
+Location and file name
+----------------------
+
+A translation mirrors the path of its original under the language
+directory, and keeps the same file name::
+
+ Documentation/process/howto.rst
+ Documentation/translations/<lang>/process/howto.rst
+
+Do not translate file or directory names. The documentation build uses
+this mapping to add, at the top of every page, links to the same page in
+the other languages; it only works if the paths match.
+
+The file header
+---------------
+
+Start the file with the same SPDX license identifier as the original.
+Most translations then indicate, in some form, which document was
+translated and include the language's disclaimer. For example, the
+Italian translation uses::
+
+ .. include:: ../disclaimer-ita.rst
+
+ :Original: Documentation/core-api/symbol-namespaces.rst
+
+A plain path is enough in the ``:Original:`` field: the documentation
+build turns ``Documentation/...`` paths into links automatically.
+
+The exact header differs from one language to another: some include a
+disclaimer in every file, some only on their index page, and some list
+the translators while others leave contact information to MAINTAINERS.
+Copy the header of a recently merged document in your language rather
+than inventing your own, and adjust the relative path of any
+``include::`` directive to the depth of your file.
+
+If your language lists translators in each file, avoid duplicating
+information that already lives in MAINTAINERS. Email addresses in
+documents go stale; MAINTAINERS is the place where they are kept current.
+
+Labels
+------
+
+Sphinx labels (``.. _label:``) are global to the whole documentation
+build. A label copied unchanged from the original therefore defines the
+same name twice, which breaks the build or, at best, makes references
+resolve to the wrong document.
+
+- Labels placed at the very top of a file are usually not needed at all
+ in the translation; simply drop them.
+
+- Labels that are needed, for example because other parts of the
+ translated document refer to them, must be made unique by adding a
+ language prefix. Each translation already uses one; look at existing
+ files to find it (``it_``, ``sp_``, ``cn_``, ``tw_``, ``pt_``, ...)::
+
+ .. _it_process_howto:
+
+- References to labels of the English documentation are fine and
+ expected. When the target document is not translated yet, linking to
+ the English version is the right thing to do.
+
+Citations and other named targets
+---------------------------------
+
+Named citations are global as well. If the original contains::
+
+ ... the C programming language [c-language]_ ...
+
+ .. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
+
+then a translation that keeps the name ``c-language`` produces a
+"duplicate citation" warning for every citation in the file. Add the
+language prefix to both the definitions and their uses::
+
+ ... a linguagem de programação C [pt-c-language]_ ...
+
+ .. [pt-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
+
+The same applies to any other construct that defines a name visible
+outside the file.
+
+Cross-references
+----------------
+
+Keep every cross-reference of the original, and decide for each one where
+it should point:
+
+- if the target document is already translated into your language, point
+ to the translation, so that readers stay in their language;
+
+- otherwise, keep the reference to the English document.
+
+Inside the translation directory, ``:doc:`` accepts paths relative to the
+current file, so a document in ``Documentation/translations/<lang>/process/``
+can refer to the translated ``howto.rst`` with ``:doc:`howto```. Absolute
+paths such as ``:doc:`/process/howto``` always point to the English
+documentation.
+
+Translate the visible text of a reference where appropriate, but never
+the target::
+
+ :ref:`Criando um tracepoint <process/debugging/driver_development_debugging_guide:ftrace>`
+
+What must not be translated
+---------------------------
+
+Some content has to stay exactly as it is in the original:
+
+- literal blocks (``::``), ``code-block`` directives, command lines and
+ their output, log messages and code examples; they are copied verbatim,
+ including indentation and tab characters;
+
+- identifiers: function, structure, variable and macro names, Kconfig
+ options, file names and paths, command names and options, sysfs and
+ procfs entries;
+
+- the targets of references, URLs, and the arguments of directives such
+ as ``kernel-doc``, ``include`` or ``toctree``;
+
+- the names of tags and other fixed strings that people have to type,
+ such as ``Signed-off-by:`` or ``Reviewed-by:``.
+
+The text around those elements is translated as usual. When a sentence
+quotes an identifier, keep the identifier and its markup and translate
+the rest of the sentence.
+
+Document structure and formatting
+---------------------------------
+
+Keep the structure of the original: the same sections, in the same order,
+with the same heading levels, and ideally the same paragraphs. This makes
+the translation much easier to review, and much easier to update later,
+because a change in the original maps to an obvious place in the
+translation.
+
+Follow the usual rules for kernel documentation:
+
+- wrap lines at 80 columns; literal blocks, tables and long URLs are the
+ usual exceptions;
+
+- make heading underlines (and overlines) at least as long as the heading
+ text, taking into account that East Asian characters occupy two
+ columns;
+
+- use UTF-8, without a byte order mark, and no trailing whitespace;
+
+- keep reStructuredText markup valid. Inline markup, such as emphasis or
+ inline literals, must be separated from the surrounding text by
+ whitespace or punctuation, and the word order of a translation can
+ change what surrounds it. When markup has to be followed directly by
+ text, separate them with an escaped space (a backslash followed by a
+ space), which does not appear in the output::
+
+ ``vmstat``\ *, mas por processo*
+
+If something really needs to be explained to readers of the translation,
+such as a term that has no established equivalent, mark it clearly as a
+translator's note (``.. note::``) instead of mixing it into the translated
+text. Use such notes sparingly; they are not a way to add content.
+
+
+Translation quality
+===================
+
+Faithfulness
+------------
+
+Compare your translation with the original paragraph by paragraph before
+sending it. Look for:
+
+- sentences or list items that were skipped or added;
+
+- statements whose meaning has shifted, for example a relative pronoun
+ that refers to a different noun after translation, or a "should" that
+ became a "must";
+
+- numbers, versions, option names and paths that changed while being
+ retyped.
+
+Terminology
+-----------
+
+Use the same terms as the rest of the translation into your language.
+Before choosing a translation for a technical term, search the existing
+documents::
+
+ $ git grep -i "<term>" Documentation/translations/<lang>/
+
+Some teams maintain a glossary (for example
+Documentation/translations/zh_CN/glossary.rst); follow it if there is
+one. Many English terms (kernel, patch, commit, driver, ...) are commonly
+used as they are by developers who speak other languages, and the
+translation should follow the established usage of the community rather
+than force a literal equivalent.
+
+If you disagree with an established term, propose a change separately,
+for the whole translation, instead of introducing a second term in a new
+document.
+
+Language
+--------
+
+Write natural, grammatically correct text in your language. A reviewer
+who has to correct agreement, punctuation or word order in every
+paragraph cannot pay attention to the content. Reading the rendered HTML
+page, rather than the source file, is a good way to catch awkward
+sentences.
+
+Machine translation and AI tools
+--------------------------------
+
+You are responsible for every word you submit. If you use machine
+translation or an AI assistant, review and correct the result as
+carefully as if you had written it yourself; translations submitted
+without that work are unlikely to be accepted, and reviewers may ask how
+a translation was produced.
+
+The rules in Documentation/process/coding-assistants.rst apply to
+translations as to any other contribution; in particular, the
+``Signed-off-by:`` tag can only be added by the human who certifies the
+contribution.
+
+
+Adding the document to the build
+================================
+
+A new document has to be listed in a ``toctree``, or Sphinx warns that it
+"isn't included in any toctree" and readers cannot find it.
+
+Add it to the ``index.rst`` of the directory in your language, in the
+same position it occupies in the English ``index.rst``. If the
+directory does not exist yet in your translation, create it with an
+``index.rst`` of its own and link that index from the parent one.
+
+Some translations keep a list of documents that are not translated yet
+in their index files. If yours does, remove the document from that list
+in the same patch.
+
+
+Building and checking your work
+===============================
+
+Build the documentation
+-----------------------
+
+Build the complete HTML documentation and make sure your change does not
+introduce any new warning::
+
+ $ make htmldocs
+
+Building only a subdirectory with ``SPHINXDIRS`` is faster, and fine
+while you are working::
+
+ $ make SPHINXDIRS=translations/<lang> htmldocs
+
+but it is not enough before sending. Such a partial build does not
+contain the English documents, so it cannot detect duplicate labels or
+citations, and it reports every reference to an English document as
+unknown, which hides real problems among the noise.
+
+The full build of the tree already produces some warnings that have
+nothing to do with your change. The simplest way to check that you did
+not add any is to compare the warnings before and after your patch::
+
+ $ make cleandocs && make htmldocs 2>&1 | tee ../before.log
+ $ git am my-translation.patch # or switch to your branch
+ $ make cleandocs && make htmldocs 2>&1 | tee ../after.log
+ $ diff <(grep -E 'WARNING|ERROR' ../before.log | sort) \
+ <(grep -E 'WARNING|ERROR' ../after.log | sort)
+
+``make cleandocs`` matters: Sphinx only rebuilds the files that changed,
+so an incremental build does not repeat warnings for files it skipped.
+
+Look at the result
+------------------
+
+Open the generated page, under ``Documentation/output/``, in a browser.
+Check that headings, lists, tables, literal blocks and links render as
+intended, and that the language links at the top of the page lead to the
+original and to the other translations of the same document.
+
+For languages that need special fonts, it is also worth building the PDF
+output (``make pdfdocs``) from time to time.
+
+Run checkpatch
+--------------
+
+Run ``scripts/checkpatch.pl`` on your patch and fix what it reports::
+
+ $ scripts/checkpatch.pl --strict -g HEAD
+
+The warnings most often seen on translation patches are:
+
+- a missing SPDX license identifier;
+
+- lines longer than the limit;
+
+- a missing commit description;
+
+- "added, moved or deleted file(s), does MAINTAINERS need updating?";
+ this one can be ignored when the translation directory is already
+ covered by a MAINTAINERS entry, which is the case for all existing
+ translations.
+
+
+Preparing the patch
+===================
+
+Scope
+-----
+
+Send one document per patch. Several related documents can be sent as a
+patch series, with one patch per document.
+
+Never mix changes to the English documentation and to a translation in
+the same patch. They are reviewed by different people, and the English
+change may need several revisions before the translation can follow it.
+
+Subject line
+------------
+
+Use the prefix that your translation already uses; ``git log --oneline
+-- Documentation/translations/<lang>/`` shows it. Examples of prefixes
+currently in use are ``docs/zh_CN:``, ``docs/zh_TW:``, ``doc:it_IT:`` and
+``docs: pt_BR:``. Then describe the change briefly::
+
+ docs: pt_BR: translate process/programming-language.rst
+
+Commit message
+--------------
+
+Write the commit message in English, so that everybody involved in
+merging the patch can read it. Say which document is translated or
+updated, and on which state of the original the translation is based.
+The ``checktransupdate.py`` script recognizes this sentence, followed by
+the abbreviated (12-character) hash and the subject of the last commit
+that changed the original::
+
+ Update the translation through commit 1234567890ab
+ ("docs: some subject of the last change to the original")
+
+With it, the script can tell exactly which changes to the original are
+still missing from the translation, even if the translation was written
+long after that commit. The hash and subject are shown by::
+
+ $ git log -1 --format='%h ("%s")' --abbrev=12 -- Documentation/<path>.rst
+
+Tags
+----
+
+The tags of a patch go in a single block at the end of the commit
+message, without blank lines between them. Git only parses the last
+paragraph of the message as trailers, so a blank line in the middle makes
+it ignore the tags above it::
+
+ Reviewed-by: Some Reviewer <reviewer@example.org>
+ Signed-off-by: Your Name <you@example.org>
+
+``Signed-off-by:`` must carry your real name; see "Sign your work - the
+Developer's Certificate of Origin" in
+Documentation/process/submitting-patches.rst.
+
+When you send a new version of a patch, keep the ``Reviewed-by:`` and
+``Acked-by:`` tags you received for it, unless the patch changed
+significantly since they were given.
+
+
+Sending the patch
+=================
+
+Recipients
+----------
+
+Run ``scripts/get_maintainer.pl`` on the patch to get the list of
+recipients::
+
+ $ scripts/get_maintainer.pl 0001-docs-pt_BR-translate-something.patch
+
+For a translation this normally includes the maintainers of the
+translation, the documentation maintainer and the linux-doc mailing list.
+Send the patch to all of them; leaving out the documentation maintainer,
+who applies most translation patches, is a common way of getting a patch
+ignored.
+
+Sending
+-------
+
+Send the patch with ``git send-email``, or with a mail client that does
+not alter it. It is a good idea to send it to yourself first and check
+that it applies cleanly with ``git am`` on top of the branch you used as
+a base.
+
+Mention below the ``---`` line anything that reviewers should know but
+that should not end up in the git history, such as questions about
+terms you were unsure of.
+
+New versions
+------------
+
+Reviewers will often ask for changes. Reply to their comments on the
+list, inline and in plain text, then send a new version of the patch:
+
+- mark it as such in the subject, for example ``[PATCH v2]``;
+
+- describe what changed since the previous version below the ``---``
+ line, and add links to earlier versions on lore.kernel.org::
+
+ ---
+ Changes in v2:
+ - Use "namespace de usuário", as in the other pt_BR documents.
+ - Prefix the citation names to avoid duplicates.
+
+ v1: https://lore.kernel.org/linux-doc/<message-id>/
+
+- address every comment, either by changing the patch or by explaining
+ why you did not;
+
+- do not hurry; give reviewers a day or so to comment on a version before
+ sending the next one.
+
+Do not add ``RESEND`` to the subject of a modified patch; that word is
+reserved for resubmitting a patch unchanged when it received no answer,
+as described in Documentation/process/submitting-patches.rst.
+
+
+The review process
+==================
+
+Translation patches are reviewed by the translation maintainers and by
+other speakers of the language, and are usually applied by the
+documentation maintainer once the translation maintainer is satisfied.
+A ``Reviewed-by:`` from the translation maintainer is usually the signal
+that the patch is ready.
+
+Reviewers typically check:
+
+- that the patch applies and builds without new warnings;
+
+- the file header, labels, citations and index entries described above;
+
+- faithfulness to the original;
+
+- grammar, style and consistency of terminology;
+
+- the commit message and the tags.
+
+Everyone is welcome to review translation patches. Reviews from other
+speakers of the language are valuable, and reviewing other people's work
+is also one of the best ways to learn the conventions of a translation.
+If you have checked a patch carefully and agree with it, say so with a
+``Reviewed-by:`` tag.
+
+Be patient. Translation maintainers are volunteers, and it can take a
+week or two to get an answer, more during the merge window.
+
+
+Keeping translations up to date
+===============================
+
+The English documentation changes all the time, and an outdated
+translation can be worse than none. ``tools/docs/checktransupdate.py``
+lists, for each translated file, the commits to the original that are
+not reflected in the translation yet::
+
+ $ tools/docs/checktransupdate.py -l <lang>
+ $ tools/docs/checktransupdate.py Documentation/translations/<lang>/process/howto.rst
+
+To update a translation, apply the same changes that the listed commits
+made to the original, and nothing else. Mention those commits in the
+commit message, ending with the "Update the translation through commit"
+sentence described above, so that the next run of the script starts from
+the right place.
+
+When an original document is moved or renamed, move its translation in
+the same way, so that the paths keep matching. When an original is
+removed, remove the translation as well.
+
+
+Starting a new translation
+==========================
+
+A new language is a long-term commitment: someone has to review
+contributions and keep the existing documents up to date for years.
+Before starting one, discuss it on the linux-doc mailing list.
+
+The first patch series of a new translation should contain a small number
+of carefully translated documents that build without warnings, plus the
+infrastructure that every translation needs:
+
+- a directory ``Documentation/translations/<ll_CC>/``, named after the
+ language and country codes (for example ``pt_BR``);
+
+- an ``index.rst`` for the language, with a translation of the disclaimer
+ in :ref:`Documentation/translations/index.rst <translations_disclaimer>`,
+ usually in a separate file included by the index;
+
+- an entry in the ``toctree`` of Documentation/translations/index.rst;
+
+- an entry in the ``all_languages`` dictionary of
+ ``Documentation/sphinx/translations.py``, which produces the language
+ links at the top of each page.
+
+The last two lists are sorted alphabetically by the English name of the
+language; keep them that way.
+
+Look at the index of an existing translation as a model. Note that the
+``raw:: latex`` directives found in those files select the fonts used for
+the PDF output, and that languages written with East Asian characters
+need different settings from the others.
+
+A MAINTAINERS entry for the new translation is not part of the first
+submission. It is something that is earned by demonstrated, sustained
+effort, and is best discussed with the documentation maintainer once the
+translation has been around for a while.
+
+
+Checklist
+=========
+
+Before sending a translation patch, check that:
+
+- the original document is not already translated, and nobody else is
+ working on it;
+
+- the file mirrors the path and name of the original;
+
+- the header follows the conventions of your language, starting with the
+ SPDX identifier;
+
+- top-of-file labels from the original have been removed, and every
+ remaining label and citation name carries the language prefix;
+
+- references point to translated documents where they exist, and to the
+ English ones otherwise;
+
+- literal blocks, code, identifiers and reference targets are unchanged;
+
+- the structure of the original is preserved and lines fit in 80
+ columns;
+
+- the translation is faithful, grammatically correct and uses the
+ established terminology;
+
+- the document is listed in the right ``index.rst``;
+
+- the full ``make htmldocs`` build adds no warning, and the HTML page
+ renders correctly;
+
+- ``scripts/checkpatch.pl --strict`` is clean;
+
+- the commit message is in English, describes the change and says on
+ which commit of the original the translation is based;
+
+- all tags are in one block and ``Signed-off-by:`` uses your real name;
+
+- the patch goes to everyone listed by ``scripts/get_maintainer.pl``, as
+ plain text.
diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst
index b6d24f6f1..181e45fbf 100644
--- a/Documentation/translations/index.rst
+++ b/Documentation/translations/index.rst
@@ -57,3 +57,6 @@ in a different form.
If you need to communicate with the Linux community but you do not feel
comfortable writing in English, you can ask the translation's maintainers
for help.
+
+If you want to help translate the documentation, see
+Documentation/doc-guide/translations.rst.
--
2.47.3
^ permalink raw reply related [flat|nested] 3+ messages in thread* [PATCH v2 2/2] docs: pt_BR: translate doc-guide/translations.rst
2026-10-15 12:56 [PATCH v2 0/2] docs: add a guide for translators Daniel Pereira
2026-10-15 12:56 ` [PATCH v2 1/2] docs: doc-guide: " Daniel Pereira
@ 2026-10-15 12:56 ` Daniel Pereira
1 sibling, 0 replies; 3+ messages in thread
From: Daniel Pereira @ 2026-10-15 12:56 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Shuah Khan, Randy Dunlap, Alex Shi, Yanteng Si, Dongliang Mu,
Chen-Yu Yeh, Weijie Yuan, Federico Vaga, Akira Yokosawa,
Carlos Bilbao, Avadhut Naik, linux-doc, linux-kernel
Translate the new guide for translators, added in the previous patch,
into Brazilian Portuguese. The translation is based on the original as
added by that patch; since its commit hash is only known once the series
is applied, the "Update the translation through commit" line suggested
by the guide is left out here.
Create Documentation/translations/pt_BR/doc-guide/ with an index that
lists the translated document and the ones still to be translated, and
link it from the pt_BR top-level index, in the same position as the
"Development tools and processes" section of the English index.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
Changes in v2:
- Follow the changes to the original in patch 1.
v1: https://lore.kernel.org/linux-doc/20261013003702.5824-3-danielmaraboo@gmail.com/
.../translations/pt_BR/doc-guide/index.rst | 19 +
.../pt_BR/doc-guide/translations.rst | 711 ++++++++++++++++++
Documentation/translations/pt_BR/index.rst | 11 +
3 files changed, 741 insertions(+)
create mode 100644 Documentation/translations/pt_BR/doc-guide/index.rst
create mode 100644 Documentation/translations/pt_BR/doc-guide/translations.rst
diff --git a/Documentation/translations/pt_BR/doc-guide/index.rst b/Documentation/translations/pt_BR/doc-guide/index.rst
new file mode 100644
index 000000000..557feb762
--- /dev/null
+++ b/Documentation/translations/pt_BR/doc-guide/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
+Como escrever a documentação do kernel
+======================================
+
+.. toctree::
+ :maxdepth: 1
+
+ translations
+
+Todolist:
+
+* sphinx
+* kernel-doc
+* parse-headers
+* contributing
+* maintainer-profile
+* checktransupdate
diff --git a/Documentation/translations/pt_BR/doc-guide/translations.rst b/Documentation/translations/pt_BR/doc-guide/translations.rst
new file mode 100644
index 000000000..19ba2c8ea
--- /dev/null
+++ b/Documentation/translations/pt_BR/doc-guide/translations.rst
@@ -0,0 +1,711 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+Traduzindo a documentação do kernel
+===================================
+
+A documentação do kernel é escrita em inglês, e o inglês é a única versão
+oficial dela. As traduções existem para tornar essa documentação acessível
+a quem se sente mais à vontade lendo em outro idioma; elas ficam em
+``Documentation/translations/``, com um diretório por idioma.
+
+Este documento explica como contribuir com essas traduções: como escolher
+o que traduzir, como um documento traduzido é organizado, como verificar
+o seu trabalho, como enviá-lo, o que esperar da revisão e como manter uma
+tradução atualizada depois que ela for integrada. Ele também descreve o
+que é necessário para iniciar a tradução para um novo idioma.
+
+Ele não substitui os documentos gerais sobre como contribuir com o kernel;
+um patch de tradução é um patch do kernel, e tudo o que está descrito em
+:doc:`../process/submitting-patches` se aplica a ele. O que segue se
+concentra nos detalhes específicos das traduções e nos erros que mais
+frequentemente fazem com que patches de tradução sejam devolvidos.
+
+Algumas traduções têm orientações adicionais, específicas do idioma e
+escritas nele; por exemplo, a equipe do chinês simplificado mantém
+Documentation/translations/zh_CN/how-to.rst. Onde existir um guia assim,
+leia-o também.
+
+
+Princípios
+==========
+
+Antes de começar, leia o aviso em
+:ref:`Documentation/translations/index.rst <translations_disclaimer>`.
+Seus pontos principais orientam todo o restante deste documento:
+
+- **O inglês é a referência.** Quando uma tradução e o original em inglês
+ divergem, a versão em inglês é a correta.
+
+- **Uma tradução não é um fork.** Ela não deve acrescentar, remover nem
+ alterar informações. Se você encontrar um erro, uma omissão ou uma
+ afirmação desatualizada no original, corrija primeiro o documento em
+ inglês, com um patch separado enviado aos mantenedores da documentação.
+ Depois que essa alteração for integrada, a tradução pode acompanhá-la.
+
+- **Os mantenedores das traduções só aceitam trabalho de tradução**: novas
+ traduções, atualizações que acompanham mudanças no original e correções
+ em traduções existentes.
+
+- **Adaptar é permitido; mudar o sentido, não.** Cada idioma tem sua
+ própria gramática e suas expressões, e uma tradução literal, palavra por
+ palavra, muitas vezes fica errada. Reformule o quanto o seu idioma
+ exigir, desde que o leitor termine com a mesma informação que um leitor
+ do original.
+
+
+Antes de começar
+================
+
+Encontre a equipe da tradução
+-----------------------------
+
+Cada tradução está listada no arquivo MAINTAINERS, com uma linha ``F:``
+apontando para o seu diretório. Você pode encontrar os responsáveis por
+uma tradução com::
+
+ $ scripts/get_maintainer.pl -f Documentation/translations/<lang>/
+
+Acompanhe as discussões recentes na lista de discussão linux-doc
+(https://lore.kernel.org/linux-doc/) para ter uma ideia de como a equipe
+trabalha, quais convenções segue e o que os revisores costumam pedir. Se
+estiver em dúvida sobre algo, pergunte na lista antes de investir muito
+trabalho; os mantenedores das traduções costumam ficar contentes em ajudar
+quem está começando.
+
+Escolha o que traduzir
+----------------------
+
+Bons candidatos são os documentos que muita gente lê: os documentos sobre
+o processo de desenvolvimento em ``Documentation/process/``, o guia do
+administrador e os guias sobre como escrever documentação. Documentos
+longos, que mudam com frequência ou muito especializados são mais difíceis
+de manter atualizados e é melhor deixá-los para depois.
+
+Verifique se o documento ainda não foi traduzido e se ninguém mais está
+trabalhando nele:
+
+- procure em ``Documentation/translations/<lang>/``;
+
+- pesquise o nome do arquivo no arquivo da linux-doc em lore.kernel.org;
+ um patch pendente, ou uma revisão recente, significa que alguém já está
+ cuidando dele;
+
+- use o ``tools/docs/checktransupdate.py`` para listar os documentos que
+ ainda não têm tradução::
+
+ $ tools/docs/checktransupdate.py -l <lang> --print-missing-translations
+
+ Veja Documentation/doc-guide/checktransupdate.rst para mais detalhes.
+
+Evite que várias pessoas traduzam arquivos do mesmo diretório ao mesmo
+tempo. Nesse caso, os patches tendem a alterar o mesmo ``index.rst`` e
+acabam entrando em conflito entre si. Se você pretende traduzir um
+diretório inteiro, avise na lista.
+
+Se você é novo no desenvolvimento do kernel, comece com um documento
+curto. É no primeiro patch que aparece a maioria dos problemas de
+processo, e eles são muito mais fáceis de corrigir em um arquivo de 60
+linhas do que em um de 2000.
+
+Prepare o seu ambiente
+----------------------
+
+As traduções são integradas pela árvore da documentação, então baseie o
+seu trabalho no branch ``docs-next`` dela (a linha ``T:`` da entrada
+DOCUMENTATION no MAINTAINERS indica onde ela fica)::
+
+ $ git remote add docs git://git.lwn.net/linux.git
+ $ git fetch docs
+ $ git switch -c minha-traducao docs/docs-next
+
+Algumas traduções são reunidas primeiro em uma árvore própria; se a
+entrada do MAINTAINERS do seu idioma tiver a sua própria linha ``T:``,
+pergunte aos mantenedores da tradução qual branch usar.
+
+Você vai precisar de uma instalação do Sphinx funcionando para compilar a
+documentação. O ``tools/docs/sphinx-pre-install`` verifica o seu sistema e
+informa o que está faltando; Documentation/doc-guide/sphinx.rst traz os
+detalhes.
+
+Você também vai precisar conseguir enviar e-mails em texto puro com o
+``git send-email`` ou com um cliente de e-mail configurado como descrito
+em :doc:`../process/email-clients`. As listas de discussão do
+vger.kernel.org rejeitam e-mails em HTML, então respostas enviadas por uma
+interface de webmail na configuração padrão nunca chegam à lista.
+
+
+Anatomia de um documento traduzido
+==================================
+
+Localização e nome do arquivo
+-----------------------------
+
+Uma tradução reproduz o caminho do seu original dentro do diretório do
+idioma e mantém o mesmo nome de arquivo::
+
+ Documentation/process/howto.rst
+ Documentation/translations/<lang>/process/howto.rst
+
+Não traduza nomes de arquivos nem de diretórios. A compilação da
+documentação usa essa correspondência para adicionar, no topo de cada
+página, links para a mesma página nos outros idiomas; isso só funciona se
+os caminhos coincidirem.
+
+O cabeçalho do arquivo
+----------------------
+
+Comece o arquivo com o mesmo identificador de licença SPDX do original. A
+maioria das traduções indica em seguida, de alguma forma, qual documento
+foi traduzido e inclui o aviso do idioma. Por exemplo, a tradução para o
+italiano usa::
+
+ .. include:: ../disclaimer-ita.rst
+
+ :Original: Documentation/core-api/symbol-namespaces.rst
+
+Um caminho simples basta no campo ``:Original:``: a compilação da
+documentação transforma automaticamente os caminhos ``Documentation/...``
+em links.
+
+O cabeçalho exato varia de um idioma para outro: alguns incluem o aviso em
+todos os arquivos, outros apenas na página de índice, e alguns listam os
+tradutores enquanto outros deixam as informações de contato para o
+MAINTAINERS. Copie o cabeçalho de um documento integrado recentemente no
+seu idioma, em vez de inventar o seu, e ajuste o caminho relativo de
+qualquer diretiva ``include::`` à profundidade do seu arquivo.
+
+Se o seu idioma lista os tradutores em cada arquivo, evite duplicar
+informações que já estão no MAINTAINERS. Endereços de e-mail em documentos
+ficam desatualizados; o MAINTAINERS é o lugar onde eles são mantidos em
+dia.
+
+Rótulos
+-------
+
+Os rótulos do Sphinx (``.. _rotulo:``) são globais para toda a compilação
+da documentação. Um rótulo copiado sem alteração do original, portanto,
+define o mesmo nome duas vezes, o que quebra a compilação ou, na melhor
+das hipóteses, faz as referências apontarem para o documento errado.
+
+- Os rótulos colocados bem no início de um arquivo normalmente não são
+ necessários na tradução; basta removê-los.
+
+- Os rótulos necessários, por exemplo porque outras partes do documento
+ traduzido se referem a eles, devem se tornar únicos com o acréscimo de
+ um prefixo do idioma. Cada tradução já usa um; veja os arquivos
+ existentes para descobrir qual (``it_``, ``sp_``, ``cn_``, ``tw_``,
+ ``pt_``, ...)::
+
+ .. _it_process_howto:
+
+- Referências a rótulos da documentação em inglês são aceitáveis e
+ esperadas. Quando o documento de destino ainda não foi traduzido, criar
+ o link para a versão em inglês é a coisa certa a fazer.
+
+Citações e outros alvos com nome
+--------------------------------
+
+As citações com nome também são globais. Se o original contém::
+
+ ... the C programming language [c-language]_ ...
+
+ .. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
+
+então uma tradução que mantém o nome ``c-language`` gera um aviso de
+"duplicate citation" para cada citação do arquivo. Acrescente o prefixo do
+idioma tanto às definições quanto aos seus usos::
+
+ ... a linguagem de programação C [pt-c-language]_ ...
+
+ .. [pt-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
+
+O mesmo vale para qualquer outra construção que defina um nome visível
+fora do arquivo.
+
+Referências cruzadas
+--------------------
+
+Mantenha todas as referências cruzadas do original e decida, para cada
+uma, para onde ela deve apontar:
+
+- se o documento de destino já estiver traduzido para o seu idioma, aponte
+ para a tradução, para que os leitores continuem no seu idioma;
+
+- caso contrário, mantenha a referência ao documento em inglês.
+
+Dentro do diretório da tradução, o ``:doc:`` aceita caminhos relativos ao
+arquivo atual; assim, um documento em
+``Documentation/translations/<lang>/process/`` pode se referir ao
+``howto.rst`` traduzido com ``:doc:`howto```. Caminhos absolutos, como
+``:doc:`/process/howto```, sempre apontam para a documentação em inglês.
+
+Traduza o texto visível de uma referência quando for adequado, mas nunca o
+seu destino::
+
+ :ref:`Criando um tracepoint <process/debugging/driver_development_debugging_guide:ftrace>`
+
+O que não deve ser traduzido
+----------------------------
+
+Alguns conteúdos precisam permanecer exatamente como estão no original:
+
+- blocos literais (``::``), diretivas ``code-block``, linhas de comando e
+ suas saídas, mensagens de log e exemplos de código; eles são copiados
+ sem alteração, incluindo a indentação e os caracteres de tabulação;
+
+- identificadores: nomes de funções, estruturas, variáveis e macros,
+ opções do Kconfig, nomes e caminhos de arquivos, nomes de comandos e
+ suas opções, entradas do sysfs e do procfs;
+
+- os destinos das referências, as URLs e os argumentos de diretivas como
+ ``kernel-doc``, ``include`` ou ``toctree``;
+
+- os nomes das tags e outros textos fixos que as pessoas precisam digitar,
+ como ``Signed-off-by:`` ou ``Reviewed-by:``.
+
+O texto ao redor desses elementos é traduzido normalmente. Quando uma
+frase cita um identificador, mantenha o identificador e a sua marcação e
+traduza o restante da frase.
+
+Estrutura e formatação do documento
+-----------------------------------
+
+Mantenha a estrutura do original: as mesmas seções, na mesma ordem, com os
+mesmos níveis de título e, de preferência, os mesmos parágrafos. Isso
+torna a tradução muito mais fácil de revisar, e muito mais fácil de
+atualizar depois, porque uma mudança no original corresponde a um lugar
+óbvio na tradução.
+
+Siga as regras habituais da documentação do kernel:
+
+- quebre as linhas em 80 colunas; blocos literais, tabelas e URLs longas
+ são as exceções habituais;
+
+- faça o sublinhado (e o sobrelinhado) dos títulos pelo menos tão longo
+ quanto o texto do título, levando em conta que os caracteres do leste
+ asiático ocupam duas colunas;
+
+- use UTF-8, sem marca de ordem de bytes (BOM) e sem espaços em branco no
+ fim das linhas;
+
+- mantenha a marcação reStructuredText válida. A marcação inline, como a
+ ênfase ou os literais inline, precisa estar separada do texto ao redor
+ por espaços ou pontuação, e a ordem das palavras de uma tradução pode
+ mudar o que fica ao redor dela. Quando a marcação precisar ser seguida
+ diretamente por texto, separe-os com um espaço escapado (uma barra
+ invertida seguida de um espaço), que não aparece na saída::
+
+ ``vmstat``\ *, mas por processo*
+
+Se algo realmente precisar ser explicado aos leitores da tradução, como um
+termo que não tem um equivalente estabelecido, marque-o claramente como
+uma nota do tradutor (``.. note::``) em vez de misturá-lo ao texto
+traduzido. Use essas notas com moderação; elas não são uma forma de
+acrescentar conteúdo.
+
+
+Qualidade da tradução
+=====================
+
+Fidelidade
+----------
+
+Compare a sua tradução com o original, parágrafo por parágrafo, antes de
+enviá-la. Procure por:
+
+- frases ou itens de lista que foram omitidos ou acrescentados;
+
+- afirmações cujo sentido mudou, por exemplo um pronome relativo que,
+ depois da tradução, passa a se referir a outro substantivo, ou um
+ "should" que virou um "must";
+
+- números, versões, nomes de opções e caminhos que mudaram ao serem
+ redigitados.
+
+Terminologia
+------------
+
+Use os mesmos termos que o restante da tradução para o seu idioma. Antes
+de escolher uma tradução para um termo técnico, pesquise nos documentos
+existentes::
+
+ $ git grep -i "<termo>" Documentation/translations/<lang>/
+
+Algumas equipes mantêm um glossário (por exemplo,
+Documentation/translations/zh_CN/glossary.rst); siga-o, se houver um.
+Muitos termos em inglês (kernel, patch, commit, driver, ...) costumam ser
+usados como estão por desenvolvedores que falam outros idiomas, e a
+tradução deve seguir o uso estabelecido pela comunidade em vez de impor um
+equivalente literal.
+
+Se você discorda de um termo estabelecido, proponha a mudança
+separadamente, para toda a tradução, em vez de introduzir um segundo termo
+em um documento novo.
+
+Idioma
+------
+
+Escreva um texto natural e gramaticalmente correto no seu idioma. Um
+revisor que precisa corrigir concordância, pontuação ou ordem das
+palavras em cada parágrafo não consegue prestar atenção ao conteúdo. Ler a
+página HTML gerada, em vez do arquivo-fonte, é uma boa forma de perceber
+frases estranhas.
+
+Tradução automática e ferramentas de IA
+---------------------------------------
+
+Você é responsável por cada palavra que envia. Se usar tradução automática
+ou um assistente de IA, revise e corrija o resultado com o mesmo cuidado
+que teria se o tivesse escrito; traduções enviadas sem esse trabalho
+dificilmente são aceitas, e os revisores podem perguntar como uma tradução
+foi produzida.
+
+As regras de :doc:`../process/coding-assistants` valem para as traduções
+como para qualquer outra contribuição; em particular, a tag
+``Signed-off-by:`` só pode ser adicionada pela pessoa que certifica a
+contribuição.
+
+
+Adicionando o documento à compilação
+====================================
+
+Um documento novo precisa estar listado em um ``toctree``; caso contrário,
+o Sphinx avisa que ele "isn't included in any toctree" e os leitores não
+conseguem encontrá-lo.
+
+Adicione-o ao ``index.rst`` do diretório no seu idioma, na mesma posição
+que ele ocupa no ``index.rst`` em inglês. Se o diretório ainda não existir
+na sua tradução, crie-o com um ``index.rst`` próprio e crie o link para
+esse índice a partir do índice do diretório acima.
+
+Algumas traduções mantêm, nos seus arquivos de índice, uma lista dos
+documentos que ainda não foram traduzidos. Se a sua mantiver, remova o
+documento dessa lista no mesmo patch.
+
+
+Compilando e verificando o seu trabalho
+=======================================
+
+Compile a documentação
+----------------------
+
+Compile a documentação HTML completa e verifique que a sua mudança não
+introduz nenhum aviso novo::
+
+ $ make htmldocs
+
+Compilar apenas um subdiretório com ``SPHINXDIRS`` é mais rápido, e não há
+problema em fazer isso enquanto você trabalha::
+
+ $ make SPHINXDIRS=translations/<lang> htmldocs
+
+mas não é suficiente antes do envio. Uma compilação parcial como essa não
+contém os documentos em inglês; por isso, não consegue detectar rótulos ou
+citações duplicados e informa como desconhecida toda referência a um
+documento em inglês, o que esconde os problemas reais no meio do ruído.
+
+A compilação completa da árvore já gera alguns avisos que não têm relação
+com a sua mudança. A forma mais simples de verificar que você não
+acrescentou nenhum é comparar os avisos antes e depois do seu patch::
+
+ $ make cleandocs && make htmldocs 2>&1 | tee ../antes.log
+ $ git am minha-traducao.patch # ou mude para o seu branch
+ $ make cleandocs && make htmldocs 2>&1 | tee ../depois.log
+ $ diff <(grep -E 'WARNING|ERROR' ../antes.log | sort) \
+ <(grep -E 'WARNING|ERROR' ../depois.log | sort)
+
+O ``make cleandocs`` é importante: o Sphinx só recompila os arquivos que
+mudaram, então uma compilação incremental não repete os avisos dos
+arquivos que ela ignorou.
+
+Confira o resultado
+-------------------
+
+Abra a página gerada, em ``Documentation/output/``, em um navegador.
+Verifique se títulos, listas, tabelas, blocos literais e links aparecem
+como esperado, e se os links de idioma no topo da página levam ao original
+e às outras traduções do mesmo documento.
+
+Para idiomas que precisam de fontes especiais, também vale a pena gerar a
+saída em PDF (``make pdfdocs``) de vez em quando.
+
+Rode o checkpatch
+-----------------
+
+Rode o ``scripts/checkpatch.pl`` no seu patch e corrija o que ele
+apontar::
+
+ $ scripts/checkpatch.pl --strict -g HEAD
+
+Os avisos mais comuns em patches de tradução são:
+
+- a falta do identificador de licença SPDX;
+
+- linhas mais longas que o limite;
+
+- a falta da descrição do commit;
+
+- "added, moved or deleted file(s), does MAINTAINERS need updating?";
+ este pode ser ignorado quando o diretório da tradução já é coberto por
+ uma entrada do MAINTAINERS, o que acontece com todas as traduções
+ existentes.
+
+
+Preparando o patch
+==================
+
+Escopo
+------
+
+Envie um documento por patch. Vários documentos relacionados podem ser
+enviados como uma série de patches, com um patch por documento.
+
+Nunca misture alterações na documentação em inglês e em uma tradução no
+mesmo patch. Elas são revisadas por pessoas diferentes, e a alteração em
+inglês pode precisar de várias revisões antes que a tradução possa
+acompanhá-la.
+
+Linha de assunto
+----------------
+
+Use o prefixo que a sua tradução já usa; ``git log --oneline --
+Documentation/translations/<lang>/`` o mostra. Exemplos de prefixos em uso
+atualmente são ``docs/zh_CN:``, ``docs/zh_TW:``, ``doc:it_IT:`` e
+``docs: pt_BR:``. Em seguida, descreva a mudança de forma breve::
+
+ docs: pt_BR: translate process/programming-language.rst
+
+Mensagem de commit
+------------------
+
+Escreva a mensagem de commit em inglês, para que todos os envolvidos na
+integração do patch possam lê-la. Diga qual documento foi traduzido ou
+atualizado e em qual estado do original a tradução se baseia. O script
+``checktransupdate.py`` reconhece a frase abaixo, seguida do hash
+abreviado (12 caracteres) e do assunto do último commit que alterou o
+original::
+
+ Update the translation through commit 1234567890ab
+ ("docs: some subject of the last change to the original")
+
+Com ela, o script consegue dizer exatamente quais mudanças do original
+ainda faltam na tradução, mesmo que a tradução tenha sido escrita muito
+depois desse commit. O hash e o assunto são mostrados por::
+
+ $ git log -1 --format='%h ("%s")' --abbrev=12 -- Documentation/<caminho>.rst
+
+Tags
+----
+
+As tags de um patch ficam em um único bloco no fim da mensagem de commit,
+sem linhas em branco entre elas. O git só interpreta o último parágrafo
+da mensagem como trailers, então uma linha em branco no meio faz com que
+ele ignore as tags acima dela::
+
+ Reviewed-by: Um Revisor <revisor@example.org>
+ Signed-off-by: Seu Nome <voce@example.org>
+
+O ``Signed-off-by:`` deve trazer o seu nome real; veja "Sign your work -
+the Developer's Certificate of Origin" em
+:doc:`../process/submitting-patches`.
+
+Quando você enviar uma nova versão de um patch, mantenha as tags
+``Reviewed-by:`` e ``Acked-by:`` que recebeu, a menos que o patch tenha
+mudado significativamente desde que elas foram dadas.
+
+
+Enviando o patch
+================
+
+Destinatários
+-------------
+
+Rode o ``scripts/get_maintainer.pl`` no patch para obter a lista de
+destinatários::
+
+ $ scripts/get_maintainer.pl 0001-docs-pt_BR-translate-something.patch
+
+Para uma tradução, isso normalmente inclui os mantenedores da tradução, o
+mantenedor da documentação e a lista de discussão linux-doc. Envie o patch
+para todos eles; deixar de fora o mantenedor da documentação, que aplica a
+maioria dos patches de tradução, é uma forma comum de ter um patch
+ignorado.
+
+Enviando
+--------
+
+Envie o patch com o ``git send-email`` ou com um cliente de e-mail que não
+o altere. É uma boa ideia enviá-lo primeiro para você mesmo e verificar se
+ele se aplica sem problemas com o ``git am`` sobre o branch que você usou
+como base.
+
+Mencione abaixo da linha ``---`` tudo o que os revisores devem saber, mas
+que não deve entrar no histórico do git, como dúvidas sobre termos dos
+quais você não tinha certeza.
+
+Novas versões
+-------------
+
+Os revisores muitas vezes pedem mudanças. Responda aos comentários deles
+na lista, intercalando as respostas no texto e em texto puro, e então
+envie uma nova versão do patch:
+
+- identifique-a como tal no assunto, por exemplo ``[PATCH v2]``;
+
+- descreva o que mudou desde a versão anterior abaixo da linha ``---`` e
+ acrescente links para as versões anteriores em lore.kernel.org::
+
+ ---
+ Changes in v2:
+ - Use "namespace de usuário", as in the other pt_BR documents.
+ - Prefix the citation names to avoid duplicates.
+
+ v1: https://lore.kernel.org/linux-doc/<message-id>/
+
+- trate todos os comentários, seja alterando o patch, seja explicando por
+ que não o fez;
+
+- não tenha pressa; dê aos revisores mais ou menos um dia para comentar
+ uma versão antes de enviar a próxima.
+
+Não acrescente ``RESEND`` ao assunto de um patch modificado; essa palavra
+é reservada para reenviar sem alterações um patch que não recebeu
+resposta, como descrito em :doc:`../process/submitting-patches`.
+
+
+O processo de revisão
+=====================
+
+Os patches de tradução são revisados pelos mantenedores da tradução e por
+outros falantes do idioma, e normalmente são aplicados pelo mantenedor da
+documentação depois que o mantenedor da tradução fica satisfeito. Um
+``Reviewed-by:`` do mantenedor da tradução costuma ser o sinal de que o
+patch está pronto.
+
+Os revisores normalmente verificam:
+
+- se o patch se aplica e compila sem avisos novos;
+
+- o cabeçalho do arquivo, os rótulos, as citações e as entradas de índice
+ descritos acima;
+
+- a fidelidade ao original;
+
+- a gramática, o estilo e a consistência da terminologia;
+
+- a mensagem de commit e as tags.
+
+Todos são bem-vindos para revisar patches de tradução. Revisões de outros
+falantes do idioma são valiosas, e revisar o trabalho de outras pessoas é
+também uma das melhores formas de aprender as convenções de uma tradução.
+Se você revisou um patch com cuidado e concorda com ele, diga isso com uma
+tag ``Reviewed-by:``.
+
+Tenha paciência. Os mantenedores das traduções são voluntários, e pode
+levar uma ou duas semanas para receber uma resposta, mais durante a janela
+de merge.
+
+
+Mantendo as traduções atualizadas
+=================================
+
+A documentação em inglês muda o tempo todo, e uma tradução desatualizada
+pode ser pior do que nenhuma. O ``tools/docs/checktransupdate.py`` lista,
+para cada arquivo traduzido, os commits no original que ainda não estão
+refletidos na tradução::
+
+ $ tools/docs/checktransupdate.py -l <lang>
+ $ tools/docs/checktransupdate.py Documentation/translations/<lang>/process/howto.rst
+
+Para atualizar uma tradução, aplique as mesmas mudanças que os commits
+listados fizeram no original, e nada além disso. Mencione esses commits na
+mensagem de commit, terminando com a frase "Update the translation through
+commit" descrita acima, para que a próxima execução do script comece do
+ponto certo.
+
+Quando um documento original for movido ou renomeado, mova a tradução da
+mesma forma, para que os caminhos continuem coincidindo. Quando um
+original for removido, remova também a tradução.
+
+
+Iniciando uma nova tradução
+===========================
+
+Um novo idioma é um compromisso de longo prazo: alguém precisa revisar as
+contribuições e manter os documentos existentes atualizados por anos.
+Antes de iniciar um, discuta a ideia na lista de discussão linux-doc.
+
+A primeira série de patches de uma nova tradução deve conter um pequeno
+número de documentos traduzidos com cuidado, que compilem sem avisos, além
+da infraestrutura de que toda tradução precisa:
+
+- um diretório ``Documentation/translations/<ll_CC>/``, com o nome formado
+ pelos códigos do idioma e do país (por exemplo, ``pt_BR``);
+
+- um ``index.rst`` para o idioma, com uma tradução do aviso de
+ :ref:`Documentation/translations/index.rst <translations_disclaimer>`,
+ normalmente em um arquivo separado incluído pelo índice;
+
+- uma entrada no ``toctree`` de Documentation/translations/index.rst;
+
+- uma entrada no dicionário ``all_languages`` de
+ ``Documentation/sphinx/translations.py``, que gera os links de idioma no
+ topo de cada página.
+
+Essas duas últimas listas são ordenadas alfabeticamente pelo nome do
+idioma em inglês; mantenha-as assim.
+
+Use o índice de uma tradução existente como modelo. Note que as diretivas
+``raw:: latex`` encontradas nesses arquivos selecionam as fontes usadas na
+saída em PDF, e que os idiomas escritos com caracteres do leste asiático
+precisam de configurações diferentes das dos outros.
+
+Uma entrada no MAINTAINERS para a nova tradução não faz parte do primeiro
+envio. Ela é algo que se conquista com um esforço demonstrado e
+contínuo, e é melhor discuti-la com o mantenedor da documentação depois
+que a tradução já existir há algum tempo.
+
+
+Lista de verificação
+====================
+
+Antes de enviar um patch de tradução, verifique se:
+
+- o documento original ainda não foi traduzido e ninguém mais está
+ trabalhando nele;
+
+- o arquivo reproduz o caminho e o nome do original;
+
+- o cabeçalho segue as convenções do seu idioma, começando pelo
+ identificador SPDX;
+
+- os rótulos do início do arquivo original foram removidos, e todos os
+ rótulos e nomes de citações restantes têm o prefixo do idioma;
+
+- as referências apontam para os documentos traduzidos, quando existirem,
+ e para os documentos em inglês, caso contrário;
+
+- os blocos literais, o código, os identificadores e os destinos das
+ referências estão inalterados;
+
+- a estrutura do original foi preservada e as linhas cabem em 80 colunas;
+
+- a tradução é fiel, gramaticalmente correta e usa a terminologia
+ estabelecida;
+
+- o documento está listado no ``index.rst`` correto;
+
+- a compilação completa com ``make htmldocs`` não acrescenta nenhum aviso,
+ e a página HTML aparece corretamente;
+
+- o ``scripts/checkpatch.pl --strict`` não aponta nenhum problema;
+
+- a mensagem de commit está em inglês, descreve a mudança e diz em qual
+ commit do original a tradução se baseia;
+
+- todas as tags estão em um único bloco e o ``Signed-off-by:`` usa o seu
+ nome real;
+
+- o patch é enviado, em texto puro, para todos os listados pelo
+ ``scripts/get_maintainer.pl``.
diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst
index 5557c5e4e..23d27813d 100644
--- a/Documentation/translations/pt_BR/index.rst
+++ b/Documentation/translations/pt_BR/index.rst
@@ -68,6 +68,17 @@ kernel e sobre como ver seu trabalho integrado.
process/index
+Ferramentas e processos de desenvolvimento
+==========================================
+
+Vários outros manuais com informações úteis para todos os desenvolvedores
+do kernel.
+
+.. toctree::
+ :maxdepth: 1
+
+ doc-guide/index
+
Guias do usuário e do administrador
===================================
--
2.47.3
^ permalink raw reply related [flat|nested] 3+ messages in thread