[PATCH 0/2] docs: add a guide for translators

[PATCH 0/2] docs: add a guide for translators

[Daniel Pereira]

Jonathan, apologies: an earlier test send of this series reached you
by mistake, without the lists in Cc.  This is the proper posting; please
ignore the previous one.

The documentation has seven translations, but the English documentation
has no guide on how to contribute to them; the only one that exists,
Documentation/translations/zh_CN/how-to.rst, is in Chinese and covers
zh_CN only.  As a result, the same problems keep coming up in the review
of translation patches: labels copied from the original that collide
with the English ones, partial builds that hide those collisions,
documents left out of any toctree, missing commit descriptions and
missing recipients.

Patch 1 adds Documentation/doc-guide/translations.rst, a guide that
covers the whole workflow of a translation, from choosing what to
translate to sending the patch and keeping the translation up to date.

Patch 2 translates the guide into Brazilian Portuguese.  Since it is
based on the original added by patch 1, whose commit hash is only known
once the series is applied, it does not carry the "Update the
translation through commit" line that the guide suggests.

Both patches were checked with a full "make htmldocs" build, with no new
warnings, and with scripts/checkpatch.pl --strict.

Daniel Pereira (2):
  docs: doc-guide: add a guide for translators
  docs: pt_BR: translate doc-guide/translations.rst

 Documentation/doc-guide/index.rst             |   1 +
 Documentation/doc-guide/translations.rst      | 693 +++++++++++++++++
 Documentation/translations/index.rst          |   3 +
 .../translations/pt_BR/doc-guide/index.rst    |  19 +
 .../pt_BR/doc-guide/translations.rst          | 709 ++++++++++++++++++
 Documentation/translations/pt_BR/index.rst    |  11 +
 6 files changed, 1436 insertions(+)
 create mode 100644 Documentation/doc-guide/translations.rst
 create mode 100644 Documentation/translations/pt_BR/doc-guide/index.rst
 create mode 100644 Documentation/translations/pt_BR/doc-guide/translations.rst

-- 
2.47.3

[PATCH 1/2] docs: doc-guide: add a guide for translators

[Daniel Pereira]

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>
---
 Documentation/doc-guide/index.rst        |   1 +
 Documentation/doc-guide/translations.rst | 693 +++++++++++++++++++++++
 Documentation/translations/index.rst     |   3 +
 3 files changed, 697 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..e4e695249
--- /dev/null
+++ b/Documentation/doc-guide/translations.rst
@@ -0,0 +1,693 @@
+.. 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: :ref:`Documentation/process/howto.rst <process_howto>`
+  :Translator: Alessia Mantegazza <amantegazza@vaga.pv.it>
+
+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: the use of such tools must be
+acknowledged with an ``Assisted-by:`` tag, and 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::
+
+  Assisted-by: LLM
+  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, ``Signed-off-by:`` uses your real name and
+  any use of AI tools is acknowledged with ``Assisted-by:``;
+
+- 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

[PATCH 2/2] docs: pt_BR: translate doc-guide/translations.rst

[Daniel Pereira]

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>
---
 .../translations/pt_BR/doc-guide/index.rst    |  19 +
 .../pt_BR/doc-guide/translations.rst          | 709 ++++++++++++++++++
 Documentation/translations/pt_BR/index.rst    |  11 +
 3 files changed, 739 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..edbbfdabd
--- /dev/null
+++ b/Documentation/translations/pt_BR/doc-guide/translations.rst
@@ -0,0 +1,709 @@
+.. 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: :ref:`Documentation/process/howto.rst <process_howto>`
+  :Translator: Alessia Mantegazza <amantegazza@vaga.pv.it>
+
+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: o uso dessas ferramentas deve ser
+informado com uma tag ``Assisted-by:``, e 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::
+
+  Assisted-by: LLM
+  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, o ``Signed-off-by:`` usa o seu
+  nome real e qualquer uso de ferramentas de IA está informado com
+  ``Assisted-by:``;
+
+- 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