Add Crowdin to set up translations (Qiskit#541)

Part of  Qiskit#476. 

This PR sets up two GitHub actions for interfacing with Crowdin.com, the
website the translation team uses for translations.

1. Upload English sources. We do this on any change to `docs/` (except
API docs), which the translation team so that they can start making
updates sooner. For example:

<img width="346" alt="Screenshot 2023-12-20 at 5 45 05 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/0ed4cbed-45db-45bb-9150-5d90bec7a0f6">

2. Download the translations. This happens once a week, which the
translations team requested. It will open up a pull request like
https://github.com/Eric-Arellano/documentation/pull/10.

## How auth works

We only need to set GitHub Secrets for CROWDIN_PROJECT_ID and
CROWDIN_PERSONAL_TOKEN. GitHub will automatically set GITHUB_TOKEN using
[this
mechanism](https://docs.github.com/en/actions/security-guides/automatic-token-authentication).

## Translations saved at `translations/` folder

This adds a top-level `translations/` folder, rather than nesting the
translations inside the `docs/` folder. For example:

<img width="367" alt="Screenshot 2023-12-20 at 5 48 09 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/42e27fd4-5c67-4ceb-aae3-8f25315f7aae">

This top-level folder is useful because it reduces noise in the `docs/`
folder. It makes it more obvious to the team what is the original source
docs vs. what is translations and should not be modified directly in
this repository.

### How this works with the app

To get docs previews working in this repo, we teach the Docker image to
mount `translations/` as if its contents were in the folder `docs/`,
since the application expects all content to live there.

When we sync the translations from open-source to closed-source for
production, we will copy the contents of `translations/` so that it
actually lives underneath `docs/`. For example,
`translations/es/support.mdx` becomes `docs/es/support.mdx`.

## Locales

As explained in Qiskit#7, we
generally want to use the two-letter code for languages, like `es` and
`fr`. The only exception is Chinese, where we need to distinguish
between Traditional and Simplified.

This config works with that, so long as in Crowdin.com, the project sets
up this Language Mapping under the Languages settings:

<img width="475" alt="Screenshot 2023-12-20 at 5 59 19 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/adf643d1-716a-435c-9e32-9762c6570956">

## Doesn't yet add `_languages.json`

As explained in Qiskit#7, we
will probably want a file like `_languages.json` that teaches the docs
app what each language is, such as its name to show in the language
toggle. That schema still needs to be finalized and it can be added in a
follow up.

Author: Eric-Arellano

.github/workflows/crowdin-download-translations.yml

@@ -0,0 +1,50 @@
+# This code is a Qiskit project.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# This Action downloads the translations from Crowdin once a week.
+#
+# The Translations team requested the updates to be once a week because
+# they think it's a good balance between giving enough time for translations
+# vs. the docs becoming out-of-date. This schedule can be revisited with
+# the Translations team.
+#
+# We may also want to have per-language configuration. For example, one language
+# is updated every week, whereas another every two weeks. But for now, all
+# languages are treated the same to keep things simple.
+
+name: Download Crowdin translations
+on:
+  schedule:
+    - cron: "0 5 * * 1" # Every Monday at 5:00 am UTC
+  workflow_dispatch:
+
+jobs:
+  download-translations:
+    if: github.repository_owner == 'Qiskit'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Download translations
+        uses: crowdin/github-action@v1
+        with:
+          upload_sources: false
+          upload_translations: false
+          download_sources: false
+          download_translations: true
+          project_id: ${{ secrets.CROWDIN_PROJECT_ID }}
+          token: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/crowdin-upload-english.yml

@@ -0,0 +1,47 @@
+# This code is a Qiskit project.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# This Action uploads the English documentation to Crowdin so that it can be
+# translated.
+#
+# We upload on every merge to `main` rather than batching changes.
+# The Translations team prefers that workflow: it lets them get
+# started on changes right away and makes the changes less
+# overwhelming since they're smaller.
+
+name: Upload English to Crowdin
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**/*"
+      - "!docs/api/qiskit/**/*"
+      - "!docs/api/qiskit-ibm-runtime/**/*"
+      - "!docs/api/qiskit-ibm-provider/**/*"
+  workflow_dispatch:
+
+jobs:
+  upload-english:
+    if: github.repository_owner == 'Qiskit'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Upload English
+        uses: crowdin/github-action@v1
+        with:
+          upload_sources: true
+          upload_translations: false
+          download_sources: false
+          download_translations: false
+          project_id: ${{ secrets.CROWDIN_PROJECT_ID }}
+          token: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

.github/workflows/staging.yml

@@ -24,7 +24,7 @@ on:
 
 jobs:
   deploy:
-    if: github.repository
+    if: github.repository_owner == 'Qiskit'
     uses: Qiskit/gh-actions/.github/workflows/code-engine-preview.yml@main
     with:
       code_engine_project: qiskit-docs-preview

Dockerfile

@@ -34,6 +34,7 @@
 FROM icr.io/quantum-computing/iqp-channel-docs-dev
 
 COPY docs/ /home/node/app/docs
+COPY translations/ /home/node/app/docs
 COPY public/images /home/node/app/public/images
 
 EXPOSE 3000 5001

README.md

@@ -87,18 +87,27 @@ The local preview does not include the initial index page and the top nav bar fr
 - http://localhost:3000/api/qiskit-ibm-provider
 - http://localhost:3000/api/migration-guides
 
+For historical API versions, use URLs like http://localhost:3000/api/qiskit/0.44, i.e. put the desired version after the
+API name.
+
+For translations, put the language code in front of the URL, like http://localhost:3000/es/start or http://localhost:3000/fr/start. You can find the language codes by looking in the `translations/` folder.
+
 ## Preview the docs in PRs
 
 Contributors with write access to this repository can use live previews of the docs: GitHub will deploy a website using your changes.
 
 To use live previews, push your branch to `upstream` rather than your fork. GitHub will leave a comment with the link to the site. Please prefix your branch name with your initials, e.g. `EA/fix-build-typo`, for good Git hygiene.
 
+The preview application's UI is currently out-of-date so it does not properly show certain navigation like historical API versions. Refer to [Preview the docs locally](#preview-the-docs-locally) for instructions on how to explicitly visit pages.
+
 ## Staging
 
 We also re-deploy the docs every time we merge into `main` at the site https://qiskit-docs-preview-staging.1799mxdls7qz.us-south.codeengine.appdomain.cloud.
 
 This staging environment can be useful to see how the docs are rendering before we push it live to production.
 
+The staging application's UI is currently out-of-date so it does not properly show certain navigation like historical API versions. Refer to [Preview the docs locally](#preview-the-docs-locally) for instructions on how to explicitly visit pages.
+
 ## Execute notebooks
 
 To execute notebooks in a fixed Python environment, first install `tox` using

crowdin.yml

@@ -0,0 +1,22 @@
+# Refer to https://developer.crowdin.com/configuration-file/.
+
+"preserve_hierarchy": true
+
+files:
+  [
+    {
+      "source": "docs/**/*",
+      "translation": "translations/%two_letters_code%/%original_path%/%original_file_name%",
+      "ignore":
+        [
+          "docs/api/qiskit/**/*",
+          "docs/api/qiskit-ibm-runtime/**/*",
+          "docs/api/qiskit-ibm-provider/**/*",
+        ],
+      "translation_replace": {
+          # We don't want to include the `docs/` folder in each of our translated
+          # language folders.
+          "docs/": "",
+        },
+    },
+  ]

start

@@ -13,10 +13,22 @@
 
 import subprocess
 from pathlib import Path
+from typing import Iterator
 
 PWD = Path(__file__).parent
 
 
+def translation_volume_mounts() -> Iterator[str]:
+    """Return the CLI args to mount each language in the translations/ folder.
+
+    Unlike the root `Dockerfile`, we cannot use `-v $PWD/translations:/home/node/app/docs` because
+    Docker complains that the volume is already mounted when we mount the `/docs` folder. So, instead
+    we need to be more specific to mount each language's folder.
+    """
+    for folder in PWD.glob("translations/*"):
+        yield from ["-v", f"{folder}:/home/node/app/docs/{folder.name}"]
+
+
 def main() -> None:
     subprocess.run(
         # Keep this aligned with the Dockerfile at the root of the repository.
@@ -25,6 +37,7 @@ def main() -> None:
             "run",
             "-v",
             f"{PWD}/docs:/home/node/app/docs",
+            *translation_volume_mounts(),
             "-v",
             f"{PWD}/public/images:/home/node/app/packages/preview/public/images",
             "-p",

translations/placeholder.txt

@@ -0,0 +1,2 @@
+Remove me once actual translations exist. This is only so that the translations/ folder
+is saved with Git.