Improvements to translation guides (#420)

OriolAbril · PatriLoto · web-flow · commit cfef68c2665a · 2025-11-04T18:13:15.000+01:00
* review general translation guides and add links to it

* Add Spanish translation guide

Co-authored-by: Patricia A. Loto &lt;39300655+PatriLoto@users.noreply.github.com&gt;

* include result of discussion

* add global translation guidelines

---------

Co-authored-by: Patricia A. Loto &lt;39300655+PatriLoto@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,6 +10,7 @@ NumFOCUS invites the community to make suggestions for improvements to the DISCO
   - [Problems or Issues](#problems-or-issues)
   - [Content and Design](#content-and-design)
   - [Bug Fixes](#bug-fixes)
+  - [Translations](#translations)
 - [Pull Request Guidelines](#pull-request-guidelines)
 - [Commit Messages](#commit-messages)
 - [Review Process](#review-process)
@@ -53,6 +54,10 @@ For technical issues with the book:
 - **Reference the issue** in your pull request.
 - **Test your changes locally** following our [build instructions](README.md) before submitting.
 
+#### Translations
+
+See the [translator guide](./docs/translation/Translators_Guide.md) for all details on how to contribute translations to the Cookbook.
+
 ## Pull Request Guidelines
 
 When submitting pull requests:
diff --git a/docs/translation/Translation.md b/docs/translation/Translation.md
@@ -2,7 +2,12 @@
 
 To support localization efforts, follow these steps to extract translatable strings and update translations.
 
-## Generating `.pot` Files  
+> [!IMPORTANT]
+> The target audience of this document are language coordinators. If you are interested
+> in translating or are unsure about the meaning of "language coordinator" please read
+> [the translator guide](./Translators_Guide.md) first.
+
+## Generating `.pot` Files
 
 To extract translatable text and generate `.pot` files, run:
 
@@ -24,32 +29,29 @@ sphinx-intl update -p DISCOVER/_build/gettext -l <language-code>
 Replace <language-code> with your target language (e.g., en, fr, de).
 
 ## Applying Translations
-Once .po files are updated, compile them to .mo for use in the built documentation:
+Once .po files are updated, and contain translations, you can rebuild the book to see the translations applied:
 
 ```sh
 WEBSITE_LANGUAGE=<language-code> sphinx-build -b html DISCOVER/ DISCOVER/_build/html
-
 ```
-After compiling, rebuild the book to see the translations applied:
 
-#### **Option 1: Using a Local Server**  
+### Opening the translated website preview
 
-Run the following command to start a local server:  
+#### **Option 1: Using a Local Server**
+
+Run the following command to start a local server:
 ```sh
 python -m http.server 8000 --directory DISCOVER/_build/html/
 ```
-Then, open [`http://localhost:8000`](http://localhost:8000) in your browser.  
+Then, open [`http://localhost:8000`](http://localhost:8000) in your browser.
 
-#### **Option 2: Opening the File Directly**  
+#### **Option 2: Opening the File Directly**
 
-Alternatively, you can open the book directly by navigating to:  
+Alternatively, you can open the book directly by navigating to:
 ```
 DISCOVER/_build/html/index.html
 ```
-and opening it in your browser.  
-
-
-> Note: Contributors working on multilingual support should ensure .po file updates are included in commits.
+and opening it in your browser.
 
 
 ## Translation Workflow with Transifex
@@ -78,9 +80,13 @@ To authenticate, create a ```.transifexrc``` file in your home directory. Refer
 Get your token from [Transifex Account Settings](https://app.transifex.com/user/settings/api/).
 
 
-### Step 3: Updating ```.tx/config```
+### Step 3: Updating ```.tx/config``` (optional)
 
-The ```.tx/config``` file maps source files to Transifex resources. You’ll only need to modify this whenever a new release is made:
+The ```.tx/config``` file maps source files to Transifex resources.
+The content on Transifex is only updated whenever a new release is published,
+and `.tx/config` will only need updates if the files have changed.
+Even if publishing a new release, if only the content within the files
+has changed you can skip this step.
 
 Use the CLI to register new resources:
 ```
@@ -99,17 +105,27 @@ Refer to the [Transifex CLI reference](https://developers.transifex.com/docs/cli
 ### Step 4: Pushing Source and Translation Files
 
 Perform the following steps only when a release is made:
-- Regenerate ```.po``` files using ```sphinx-gettext``` and ```sphinx-intl```.
+- Regenerate `.pot` and `.po` files using ```sphinx-gettext``` and ```sphinx-intl```.
 - Open a PR with the updated files.
 - Push to Transifex:
 ```
 tx push -s -t
 ```
 
-This uploads both source and translation files.
+This uploads both source and translation files to Transifex.
 
 ### Step 5: Pulling Translations
-To fetch updated translations from Transifex (done manually before publishing):
+Whenever there have been significant updates to the translations on Transifex
+these should be pulled locally and a PR opened against the latest published release.
+What does "significant updates" means will depend on availability of
+language coordinators and maintainers.
+
+> [!IMPORTANT]
+> Before fetching make sure you are in the `X.Y-translations` branch of the latest release.
+> Otherwise the translations being pulled won't match the content and it will be more difficult
+> to open a PR against the correct branch to get the translations deployed on the website.
+
+To fetch updated translations from Transifex:
 ```
 tx pull -a -m reviewed
 ```
diff --git a/docs/translation/Translators_Guide.md b/docs/translation/Translators_Guide.md
@@ -14,23 +14,23 @@ This guide is your companion throughout the DISCOVER Cookbook translation journe
 
 We’re inviting volunteer translators to help make the DISCOVER Cookbook accessible to communities around the world. Here's how to join:
 
-### 1. Read the Blog Post
+### Read the Blog Post
 
 The blog post is your gateway to the project. It outlines our mission to make inclusive event planning resources accessible across languages and cultures. You’ll learn about the Cookbook’s goals, the impact of translation, contributor benefits, and how to apply.
 
 🔗 [Become a Volunteer Translator](https://numfocus.medium.com/help-us-bring-the-discover-cookbook-to-the-world-become-a-volunteer-translator-efe13ee3bc0d)
 
 ---
 
-### 2. Explore the Cookbook
+### Explore the Cookbook
 
 Get familiar with the content and tone of the DISCOVER Cookbook before you begin translating.
 
 🔗 [DISCOVER Cookbook](https://discover-cookbook.numfocus.org/intro.html)
 
 ---
 
-### 3. Roles to Join
+### Translation related roles within the team
 
 To ensure smooth collaboration and high-quality translations, our Transifex team is organized into three key roles. Each plays a vital part in the localization workflow:
 
@@ -47,57 +47,51 @@ Whether you're new to localization or a seasoned polyglot, this role is a great
 
 ---
 
-#### Language Coordinator
+#### Reviewer
 
-Language Coordinators oversee translation efforts for a specific language. They act as language-level team leads, guiding contributors and ensuring consistency.
+Reviewers are the quality gatekeepers. They ensure translations are accurate, culturally appropriate, and aligned with our standards.
 
 **Responsibilities:**
 
-- Invite new members to their language team  
-- Approve or deny join requests  
-- Assign or change contributor roles  
-- Start and moderate team discussions  
 - Review and proofread translations  
-- Submit finalized translations  
+- Submit approved translations  
+- Participate in team discussions  
 
-If you're a seasoned contributor and passionate about your language, this role lets you help steward quality and collaboration.
+If you're confident in your translation skills and detail-oriented, this role is a great way to elevate the project’s quality.
 
 ---
 
-#### Reviewer
+#### Language Coordinator
 
-Reviewers are the quality gatekeepers. They ensure translations are accurate, culturally appropriate, and aligned with our standards.
+Language Coordinators oversee translation efforts for a specific language. They act as language-level team leads, guiding contributors and ensuring consistency.
 
 **Responsibilities:**
 
+- Invite new members to their language team  
+- Approve or deny join requests  
+- Assign or change contributor roles  
+- Start and moderate team discussions  
 - Review and proofread translations  
-- Submit approved translations  
-- Participate in team discussions  
+- Submit finalized translations  
 
-If you're confident in your translation skills and detail-oriented, this role is a great way to elevate the project’s quality.
+If you're a seasoned contributor and passionate about your language, this role lets you help steward quality and collaboration.
 
 ---
 
-
 > Please note, most contributors begin as Translators. As you gain experience and contribute consistently, you may be invited to take on Reviewer or Language Coordinator responsibilities. This gradual progression ensures everyone feels confident and supported in their role.
 
 ---
 
-### 4. Apply
+### Apply - Roll-in Basis
 
-Fill out the translator application form linked in the blog post  
-   - **Deadline:** Wednesday, September 24th, 2025 (AoE)  
-   - **Notification:** Wednesday, October 1st, 2025 (AoE)  
-
-----
+We are onboarding translators on a rolling basis. Once accepted, you’ll be added to the platforms and can begin contributing right away.
 
-### 5. Start Your Role
+Fill out the translator application form linked in the blog post.
 
-The translation period runs from early October to the end of October.
+----
 
-- **Translation Period:** Monday, October 6th, 2025    
+### Start Your Role
 
----
 
 ## Onboarding & Access
 
@@ -111,25 +105,43 @@ Once selected, you’ll receive access to the following platforms:
 
 > Please note, no git or GitHub knowledge is required to become a translator to DISCOVER-Cookbook
 
+Contributors will be acknowledged in the repository [README.md](../../README.md#contributors-)
+
 ---
 
 ## 🛠Instructions for Translators
 
 ### How to Use Transifex
 
-Follow the official instructions here:  
+Follow the official instructions here:
 🔗 [Guide for Translators](https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator)
 
-### GitHub Repository
+### General translation guidelines
 
-The source files and documentation are hosted on GitHub.  
-🔗 [DISCOVER Cookbook GitHub Repo](https://github.com/numfocus/DISCOVER-Cookbook)
+The Cookbook is a static website, so the content will be translated but the structure and filenames will not.
+Consequently, when translating links or cross-references, the target should not be modified:
+`[message](target)` will become `[translated message](target)`.
 
+For example:
 
----
+```none
+See more details at the [venue section](Venue.md)
+Lea más en la [sección sobre lugar de reunión](Venue.md)
+```
 
-## The Procedure – Roll-in Basis
+The exception to this would be for example Wikipedia links that are available in the translated
+language too which should be translated.
 
-We are onboarding translators on a rolling basis. Once accepted, you’ll be added to the platforms and can begin contributing right away.
+You should also aim for formatting markup like bold or italics, and parenthesis to match the source
+but defer to the specific language guidelines for exceptions to this. A common exception
+will be adding parenthesis that aren't in the source to the translation to indicate a link
+is not available in that language. Transifex generally complains when that happens but it is
+safe to ignore the warning in such cases.
+
+### Language specific translation guides
 
+The translators of each language team work together to define a style guide
+for the translation content and a glossary. Here are the available resources:
 
+* [Spanish translation guide](./es.md) (only available in Spanish)
+* Guides for other languages are on standby waiting for translators.
diff --git a/docs/translation/es.md b/docs/translation/es.md
@@ -0,0 +1,82 @@
+# Guia de traducción
+
+Este recurso ha sido adaptado principalmente de [Metadocencia](https://doi.org/10.5281/zenodo.14416731)
+y del grupo de traducción de Python [python-docs-es](https://python-docs-es.readthedocs.io/es/3.13/translation-memory.html).
+
+Recomendamos revisar el documento entero antes de empezar a traducir.
+
+
+> [!IMPORTANT]
+> Las traducciones siempre van a ser revisadas por alguna otra persona.
+> Consequentemente, si te bloqueas con algun termino o frase concreto,
+> simplemente dejalo tal cual o como un borrador de traducción e indicalo
+> para discutirlo con quien revise el contenido.
+
+## Fuentes recomendadas
+
+### Diccionario Panhispánico de dudas
+
+* https://www.rae.es/dpd/
+
+  Obra orientada a resolver dudas en diferentes áreas de la lengua española: ortografía, sintaxis, gramática...
+
+### IATE - Terminologia de la Unión Europea
+
+* https://iate.europa.eu/home
+
+  Base de datos de las traducciones oficiales de la Unión Europea. Permite búsqueda por término y sector.
+
+## Guia de estilo
+
+### Directrices generales
+
+Se priorizará la segunda persona del singular no formal más extendida **TU** frente al formal _USTED_ o al menos extendido _VOS_. Para el plural, se usará **USTEDES** en lugar de _VOSOTROS/AS_ por las mismas razones.
+
+Trabaja con un español neutro en la medida de lo posible. Evita palabras,  términos o jerga específica de una determinada región o país. 
+
+Se intentará mantener la neutralidad de genero en las expresiones cuando fuera posible. Para eso, se utilizaran pronombres como quienes, quien, alguien. Y para sustantivos colectivos, comunidad, personas o grupo.
+
+En muchos casos el mejor criterio es pensar en el vocabulario que utilizamos cuando le explicamos a otra persona, o en el trabajo. En muchas ocasiones la versión en inglés o “spanglish” de la palabra es mucho mejor que decir “ventana emergente” (para pop-up).
+
+### Títulos
+En títulos de sección o capítulo solo se usará mayúscula en la primera palabra salvo nombre propios, en contraste con el inglés, que lo hace en todas las palabras principales (es decir, todas las palabras del título excepto conectores).
+
+### Enlaces
+Para la traducción de links de artículos o sitios en inglés, se traduce el nombre del sitio o artículo y al final se agrega la leyenda: “Disponible solo en inglés”. Siempre y cuando dicho sitio no contenga la traducción al español. 
+
+Ejemplo
+
+* Enfoques inclusivos de reclutamiento y divulgación - Disponible solo en inglés. (https://www.numfocus.org/blog/inclusive-approaches-to-recruitment-outreach-notes-from-the-disc-unconference/)
+
+### Referencias bibliográficas
+
+En el caso de citas bibliográficas, se sigue la recomendación de [normas APA](https://normas-apa.org/citas/como-citar-una-fuente-de-un-idioma-extranjero-y-su-traduccion/):
+
+> la referencia para una fuente no traducida en un idioma que no sea el español debe seguir el formato de estilo APA típico para la fuente (por ejemplo, un libro). Presente el título original de la obra seguido de la traducción al español del título entre corchetes
+
+Así, por ejemplo:
+
+* Versión original:
+  - Wilkinson, M. D. et al. The FAIR Guiding Principles for scientific data management and stewardship. Sci.Data 3:160018, doi: 10.1038/sdata.2016.18 (2016)
+* Versión traducida:
+  - Wilkinson, M. D. et al. The FAIR Guiding Principles for scientific data management and stewardship [Los principios guía FAIR para gestión y administración de datos científicos]. Sci.Data 3:160018, doi: 10.1038/sdata.2016.18 (2016)
+
+
+### Siglas
+Pasar la sigla al español siempre que sea lógico. En la primera mención se incluyen términos y siglas en español e inglés.
+
+Por ejemplo,
+
+* Plan de Gestión de Software (PGS) (en inglés, Software Management Plan, SMP)
+
+A partir de la segunda aparición se menciona sola la sigla.
+
+## Glosario
+En caso de duda sobre algun término que aparezca multiples veces, se recomienda
+crear un hilo en Discord para discutir las opciones de traducción con el resto del equipo.
+
+*  **Attendee -> Asistente** Se recomienda mantener la distinción original entre participante (_participant_) y asistente (_attendee_)
+* **Cookbook -> guía**
+* **Participant -> Participante** Se recomienda mantener la distinción original entre participante (_participant_) y asistente (_attendee_)
+* **Speaker -> Ponente**
+* **Sponsor -> _sponsor_**
diff --git a/index.html b/index.html
@@ -140,7 +140,7 @@ <h2 class="h3 mb-0">Development Version</h2>
                                 <a href="https://github.com/numfocus/DISCOVER-Cookbook/issues/new?template=new_chapter_proposal.yml" class="btn btn-success btn-sm"><i class="bi bi-journal-plus me-1"></i> Write Chapter</a>
                                 <a href="https://github.com/numfocus/DISCOVER-Cookbook/issues/new?template=content_enhancement.yml" class="btn btn-outline-secondary btn-sm"><i class="bi bi-pen"></i> Improve Content</a>
                                 <a href="https://github.com/numfocus/DISCOVER-Cookbook/issues/new?template=bug_report.yml" class="btn btn-outline-danger btn-sm"><i class="bi bi-bug me-1"></i> Report Bug</a>
-                                <a href="https://github.com/numfocus/DISCOVER-Cookbook/pull/377" class="btn btn-outline-success btn-sm"><i class="bi bi-translate"></i> Help Translate</a>
+                                <a href="https://github.com/numfocus/DISCOVER-Cookbook/tree/main/docs/translation/Translators_Guide.md" class="btn btn-outline-success btn-sm"><i class="bi bi-translate"></i> Help Translate</a>
                             </div>
                         </div>
                     </div>
