Translation page (#2224)

Co-authored-by: mfwmyfacewhen <94880365+mfwmyfacewhen@users.noreply.github.com>
Co-authored-by: Jonah Aragon <jonah@triplebit.net>
Signed-off-by: Daniel Nathan Gray <dng@disroot.org>

config/mkdocs-common.yml

@@ -76,6 +76,7 @@ theme:
     - navigation.expand
     - navigation.path
     - navigation.indexes
+    - content.tabs.link
     - content.tooltips
     - search.highlight
 

config/mkdocs-offline.yml

@@ -70,6 +70,7 @@ theme:
     - navigation.tabs
     - navigation.sections
     - navigation.indexes
+    - content.tabs.link
     - content.tooltips
     - search.highlight
 
@@ -155,6 +156,7 @@ nav:
       - Writing Guide:
         - 'meta/writing-style.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - Technical Guides:
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

config/mkdocs.en.yml

@@ -154,6 +154,7 @@ nav:
       - Writing Guide:
         - 'meta/writing-style.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - Technical Guides:
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

config/mkdocs.es.yml

@@ -152,6 +152,7 @@ nav:
       - "Guía de redacción":
         - 'meta/writing-style.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - "Guías técnicas":
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

config/mkdocs.fr.yml

@@ -152,6 +152,7 @@ nav:
       - "Guide de rédaction":
         - 'meta/writing-style.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - "Guides techniques":
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

config/mkdocs.he.yml

@@ -156,6 +156,7 @@ nav:
       - Writing Guide:
         - 'meta/writing-style.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - Technical Guides:
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

config/mkdocs.it.yml

@@ -152,6 +152,7 @@ nav:
       - Guida alla scrittura:
         - 'meta/writing-style.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - Guide tecniche:
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

config/mkdocs.nl.yml

@@ -152,6 +152,7 @@ nav:
       - Schrijfgids:
         - 'meta/writing-style.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - Technische gids:
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

docs/meta/translations.md

@@ -0,0 +1,77 @@
+---
+title: Translations
+---
+
+Crowdin has good documentation, and we suggest looking at their [Getting Started](https://support.crowdin.com/crowdin-intro/) guide. Our site is largely written in [Markdown](https://en.wikipedia.org/wiki/Markdown), so it should be easy to contribute. This page contains some helpful pointers for translating some specific syntax you may encounter on our site.
+
+Please join our localization room on Matrix ([#pg-i18n:aragon.sh](https://matrix.to/#/%23pg-i18n:aragon.sh)) if you have any additional questions, and read our [announcement blog post](https://blog.privacyguides.org/2023/02/26/i18n-announcement/) for additional information about the project.
+
+Note that the English version of the site is the primary version, meaning changes occur there first. If you notice a language falling behind the English version, please help out. We cannot guarantee the accuracy of all our translations. If you have a suggestion about content specific to your region, please open an issue or pull request to our [main repository](https://github.com/privacyguides/privacyguides.org).
+
+## Admonitions
+
+Throughout the site we use MkDocs's [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage), to show information to readers. They come in a few different flavors such as `example`, `warning`, `tip`, etc.
+
+When admonitions are used they will have an English string on the site by default. This can be [customized](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#changing-the-title), without too much effort. For example, if you were translating an admonition of type [`warning`](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#type:warning) to Dutch, this is how you would write it:
+
+=== "Dutch translation"
+
+    ```text
+    !!! warning "Waarschuwing"
+    ```
+
+=== "English source text"
+
+    ```text
+    !!! warning
+    ```
+
+Downloads are a [custom admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions) which is written as follows:
+
+=== "Dutch translation"
+
+    ```text
+    ??? downloads "Downloaden"
+    ```
+
+=== "English source text"
+
+    ```text
+    ??? downloads
+    ```
+
+The same goes for other types, such as `tip`, `example`, `warning`, `danger` etc.
+
+Recommendations are a special type of admonition which do **not** need overriding as they have no visible text, so they are never changed:
+
+=== "Dutch translation"
+
+    ```text
+    !!! recommendation
+    ```
+
+=== "English source text"
+
+    ```text
+    !!! recommendation
+    ```
+
+## Translation output
+
+Translation software gets the translation quite accurate; however, you need to make sure the translated string is correct.
+
+For example:
+
+```text
+![Software logo](assets/img/path/to/image.svg){ align=right }
+```
+
+We have sometimes found that the syntax for inserting an image like above was missing the `![` or an extra space was placed between the text and the path, e.g. `](`. If a translation string is clearly not correct, we encourage you to **delete** it by pressing the trash icon [or vote](https://support.crowdin.com/enterprise/getting-started-for-volunteers/#voting-view) on which one you think sounds best. When invalid strings are deleted, they are removed from the organization's [translation memory](https://support.crowdin.com/enterprise/translation-memory), meaning that when the source string is seen again, it won't suggest the incorrect translation.
+
+## Punctuation
+
+For examples like the above admonitions, quotation marks, e.g.: `" "` must be used to specify string text. MkDocs will not correctly interpret other symbols i.e., `「 」` or `« »`. Other punctuation marks are fine for marking regular quotations within the text otherwise.
+
+## Brackets
+
+Markdown links must use brackets i.e. `[Example link](https://example.com)`. CJK style brackets such as `（ ）` will not work for links. Crowdin will often handle links automatically, but you may encounter these links inside admonitions and other customized blocks of text.

includes/strings.en.yml

@@ -46,4 +46,4 @@ nav:
 
 site:
   translation: |
-    You're viewing the English copy of Privacy Guides, translated by our fantastic language team on Crowdin. If you notice an error, or see any untranslated sections on this page, please consider helping out!
+    You're viewing the English copy of Privacy Guides, translated by our fantastic language team on Crowdin. If you notice an error, or see any untranslated sections on this page, please consider helping out! For more information and tips see our translation guide.

theme/main.html

@@ -111,23 +111,28 @@
     {% include "partials/comments.html" %}
     {% if config.theme.language == "es" %}
     <div class="admonition info">
-    <p>Está viendo la copia en español de Privacy Guides, traducidas por nuestro fantástico equipo lingüístico en <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. Si nota un error o ve alguna sección sin traducir en esta página, ¡<a href="https://matrix.to/#/#pg-i18n:aragon.sh">considere ayudar</a>!</p>
+    <p>Está viendo la copia en español de Privacy Guides, traducidas por nuestro fantástico equipo lingüístico en <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. Si nota un error o ve alguna sección sin traducir en esta página, ¡<a href="https://matrix.to/#/#pg-i18n:aragon.sh">considere ayudar</a>! Para obtener más información y consejos, consulte nuestra <a href="/meta/translation.md">guía de traducción</a>.</p>
-    <p>You're viewing the Spanish copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a>!</p>
+    <p>You're viewing the Spanish copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a>! For more information and tips see our <a href="/meta/translation.md">translation guide</a>.</p>
     </div>
     {% elif config.theme.language == "fr" %}
     <div class="admonition info">
-    <p>Vous êtes en train de consulter la copie française de Privacy Guides, traduite par notre fantastique équipe de traducteurs sur <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. Si vous remarquez une erreur, ou si vous voyez des sections non traduites sur cette page, <a href="https://matrix.to/#/#pg-i18n:aragon.sh">n'hésitez pas à nous aider</a> !</p>
+    <p>Vous êtes en train de consulter la copie française de Privacy Guides, traduite par notre fantastique équipe de traducteurs sur <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. Si vous remarquez une erreur, ou si vous voyez des sections non traduites sur cette page, <a href="https://matrix.to/#/#pg-i18n:aragon.sh">n'hésitez pas à nous aider</a>! Pour plus d'informations et de conseils, consultez notre <a href="/meta/translation.md">guide de traduction</a>.</p>
-    <p>You're viewing the French copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a>!</p>
+    <p>You're viewing the French copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a>! For more information and tips see our <a href="/meta/translation.md">translation guide</a>.</p>
     </div>
     {% elif config.theme.language == "he" %}
     <div class="admonition info">
-    <p>אתה צופה בעותק העברי של Privacy Guides, שתורגם על ידי צוות השפה הפנטסטי שלנו ב-<a href="https://crowdin.com/project/privacyguides">Crowdin</a>. אם אתה מבחין בשגיאה, או רואה קטעים לא מתורגמים בדף זה, <a href="https://matrix.to/#/#pg-i18n:aragon.sh">אנא שקול לעזור!</a></p>
+    <p>אתה צופה בעותק העברי של Privacy Guides, שתורגם על ידי צוות השפה הפנטסטי שלנו ב-<a href="https://crowdin.com/project/privacyguides">Crowdin</a>. אם אתה מבחין בשגיאה, או רואה קטעים לא מתורגמים בדף זה, <a href="https://matrix.to/#/#pg-i18n:aragon.sh">אנא שקול לעזור</a>! למידע נוסף וטיפים עיין ב<a href="/meta/translation.md">מדריך התרגום שלנו</a>. </p>
-    <p>You're viewing the Hebrew copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a></p>
+    <p>You're viewing the Hebrew copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a>! For more information and tips see our <a href="/meta/translation.md">translation guide</a>.</p>
+    </div>
+    {% elif config.theme.language == "it" %}
+    <div class="admonition info">
+    <p>Stai visualizzando la versione italiana di Privacy Guides, tradotta dal nostro fantastico team linguistico su <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. Se noti un errore o vedi sezioni non tradotte in questa pagina, ti invitiamo a <a href="https://matrix.to/#/#pg-i18n:aragon.sh">dare una mano</a>! Per ulteriori informazioni e consigli consulta la <a href="/meta/translation.md">nostra guida alla traduzione</a>.</p>
+    <p>You're viewing the Italian copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a>! For more information and tips see our <a href="/meta/translation.md">translation guide</a>.</p>
     </div>
     {% elif config.theme.language == "nl" %}
     <div class="admonition info">
-    <p>Je bekijkt de Nederlandse versie van Privacy Guides, vertaald door ons fantastische taalteam op <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. Als u een fout opmerkt of onvertaalde gedeelten op deze pagina ziet, <a href="https://matrix.to/#/#pg-i18n:aragon.sh">overweeg dan om te helpen</a>!</p>
+    <p>Je bekijkt de Nederlandse versie van Privacy Guides, vertaald door ons fantastische taalteam op <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. Als u een fout opmerkt of onvertaalde gedeelten op deze pagina ziet, <a href="https://matrix.to/#/#pg-i18n:aragon.sh">overweeg dan om te helpen</a>! Voor meer informatie en tips zie onze <a href="/meta/translation.md">vertaalgids</a>.</p>
-    <p>You're viewing the Dutch copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a></p>
+    <p>You're viewing the Dutch copy of Privacy Guides, translated by our fantastic language team on <a href="https://crowdin.com/project/privacyguides">Crowdin</a>. If you notice an error, or see any untranslated sections on this page, please consider <a href="https://matrix.to/#/#pg-i18n:aragon.sh">helping out</a>! For more information and tips see our <a href="/meta/translation.md">translation guide</a>.</p>
     </div>
     {% endif %}
 {% endblock %}