[[guidelines-translating]]
=== Translation Guidelines

[role="summary"]
Guidelines for translators of the project_name to follow.

*Note: This is a rough draft still!*

* When translating, follow the standard glossary of terminology translations
that your language team has set up for the project_name, so that consistency is
maintained across the entire book.

* You may feel free to communicate on translation issues for the project_name
either in English, or in the language you are translating into.

* Be careful not to change any AsciiDoc formatting. See <<formatting>> for
details.

* Be careful not to change any IDs -- these should stay in English (they are not
visible to the reader). IDs come in two places/types:
** The topic ID at the top of each topic file, which looks like
  `[[id-goes-here]]`.
** Topic IDs used in cross-links, which look like either `<<id-goes-here>>`
  without link text, and `<<id-goes-here,overridden link text>>`. In the second
  format, you should translate the overridden link text, but not the ID.

* Be careful not to change any image file names, for embedded images. The
image embedding lines look like:
`image:images/spreadsheet.png["Screen shot of the tracking spreadsheet",width="100%"]`
You will need to translate the "alt" text, such as (in this example) "Screen
shot of the tracking spreadsheet".

* Be sure to look at the *images* carefully and note on your issue if there are
any problems, such as:
 ** Bad cropping (too much white space or important things cut off)
 ** Bad magnification on the page
 ** Untranslated English text that should be in your language
 ** Text entered in forms in the image that doesn't match the instructions

* If there is a Glossary topic, you will need to re-alphabetize it after
translating the terms and definitions.

* The Index will automatically be re-alphabetized, but you will need to
translate index entries. These are located at the top of each topic, and look
like `(((Main entry,secondary entry)))`.

* *Additional references section in some topics:* This section is for links to
outside references, and most or all are in English. Translators will need to
replace the references with references in their language if possible. If you are
not able to find reference links in your language, and feel that the English
references are still useful to include (or want to include references in a third
language), make sure to include a note with each reference that is not in the
language you are translated into. For instance, it might say:
----
https://www.drupal.org/documentation/modules/block[_Drupal.org_ community
documentation page "Working with blocks (content in regions)" (in English)]
----

* *Attributions information:* There may be attributions information at the
bottom of topic files, as well as in a book-wide _attributions.txt_ file. When
translating attributions information, do not translate people's names, URLs, or
company names. Your language version of the book will also need to have
additional attributions added for the translation team for your language.


*Attributions*

Written/edited by
https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon] and
https://www.drupal.org/u/eojthebrave[Joe Shindelar].
