feat: multilingual docs (#2522)

.github/CODEOWNERS

@@ -4,3 +4,9 @@
 /discord/ext/testing/ @Pycord-Development/maintain-tests
 /discord/ext/bridge/ @Pycord-Development/maintain-ext-bridge
 /.github/ @Pycord-Development/project-leads
+/docs/locales/ @Pycord-Dvelopment/maintain-translations
+/docs/build/locales/ @Pycord-Dvelopment/maintain-translations
+/.github/workflows/docs-localization-download.yml @Pycord-Dvelopment/maintain-translations
+/.github/workflows/docs-localization-upload.yml @Pycord-Dvelopment/maintain-translations
+/crowdin.yml @Pycord-Dvelopment/maintain-translations
+/requirements/_locale.txt @Pycord-Dvelopment/maintain-translations

.github/workflows/docs-localization-download.yml

@@ -0,0 +1,54 @@
+name: Multilingual Docs Download
+
+on:
+  workflow_dispatch:
+
+jobs:
+  localizse:
+    permissions: write-all
+    name: "Localisize Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: "Install Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: "requirements/_locale.txt"
+      - name: "Install Dependencies"
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -r requirements/_locale.txt
+          pip install .[speed,voice,docs]
+      - name: "Get locales"
+        run: |
+          make html
+          sphinx-build -b gettext . ./build/locales
+        working-directory: ./docs
+      - name: "Build locales"
+        run:
+          sphinx-intl update -p ./build/locales -l de -l ja -l de -l ja -l fr -l it -l
+          hi -l ko -l pt -l es -l zh
+        working-directory: ./docs
+      - name: "Crowdin"
+        uses: crowdin/github-action@v2
+        with:
+          upload_sources: false
+          upload_translations: false
+          download_translations: false
+          download_bundle: ${{ secrets.CROWDIN_BUNDLE_ID }}
+          localization_branch_name: l10n_master
+          create_pull_request: true
+          pull_request_title: "New Crowdin Translations"
+          pull_request_body:
+            "New Crowdin translations by [Crowdin GH
+            Action](https://github.com/crowdin/github-action)"
+          pull_request_base_branch_name: "master"
+          pull_request_reviewers: "Lulalaby"
+          config: "crowdin.yml"
+          base_path: "."
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_API_TOKEN }}

.github/workflows/docs-localization-upload.yml

@@ -0,0 +1,48 @@
+name: Multilingual Docs Upload
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  localizse:
+    permissions: write-all
+    name: "Localisize Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: "Install Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: "requirements/_locale.txt"
+      - name: "Install Dependencies"
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -r requirements/_locale.txt
+          pip install .[speed,voice,docs]
+      - name: "Get locales"
+        run: |
+          make html
+          sphinx-build  -b gettext . ./build/locales
+        working-directory: ./docs
+      - name: "Build locales"
+        run:
+          sphinx-intl update -p ./build/locales -l de -l ja -l de -l ja -l fr -l it -l
+          hi -l ko -l pt -l es -l zh
+        working-directory: ./docs
+      - name: "Crowdin"
+        uses: crowdin/github-action@v2
+        with:
+          upload_sources: true
+          upload_translations: false
+          download_translations: false
+          localization_branch_name: l10n_master
+          create_pull_request: false
+          config: "crowdin.yml"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_API_TOKEN }}

.github/workflows/test.yml

@@ -58,7 +58,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.12"
           cache: "pip"
           cache-dependency-path: "requirements/docs.txt"
           check-latest: true

.github/workflows/todo.yml

@@ -13,3 +13,4 @@ jobs:
           SHA: ${{ github.sha }}
           REF: ${{ github.ref }}
           COMMENT_ON_ISSUES: true
+          EXCLUDE_PATTERN: "\\.(doctree|doctrees|pickle)$"

.github/workflows/version-updates.yml

@@ -8,7 +8,7 @@ permissions:
 jobs:
   auto-merge:
     runs-on: ubuntu-latest
-    if: ${{ github.actor == 'dependabot[bot]' }}
+    if: ${{ github.actor == 'dependabot[bot]' || github.actor == 'crowdin-bot' }}
     steps:
       - run: gh pr review --approve "$PR_URL"
         env:

.gitignore

@@ -8,7 +8,8 @@ __pycache__/
 
 # Distribution / packaging
 .Python
-build/
+./build/
+./_build/
 develop-eggs/
 dist/
 downloads/
@@ -51,10 +52,6 @@ coverage.xml
 .pytest_cache/
 cover/
 
-# Translations
-*.mo
-*.pot
-
 # Django stuff:
 *.log
 local_settings.py
@@ -165,17 +162,16 @@ cython_debug/
 *.egg-info
 .venv/
 docs/_build
-docs/crowdin.py
 *.buildinfo
-*.mp3
-*.m4a
-*.wav
-*.mp4
-*.ogg
-*.pcm
-*.png
-*.jpg
-*.flac
+!*.mp3
+!*.m4a
+!*.wav
+!*.mp4
+!*.ogg
+!*.pcm
+!*.png
+!*.jpg
+!*.flac
 .vs/
 .DS_Store
 __pycache__
@@ -186,3 +182,12 @@ node_modules/*
 
 # changelog is autogenerated from CHANGELOG.md
 docs/changelog.md
+
+# Translations
+docs/build/html
+docs/build/doctrees
+!docs/build/locales/*
+*.mo
+!docs/locales/*
+/build/
+/vscode/

.pre-commit-config.yaml

@@ -7,7 +7,9 @@ repos:
     rev: v4.6.0
     hooks:
       - id: trailing-whitespace
+        exclude: \.(po|pot)$
       - id: end-of-file-fixer
+        exclude: \.(po|pot)$
   - repo: https://github.com/PyCQA/autoflake
     rev: v2.3.1
     hooks:
@@ -19,19 +21,21 @@ repos:
   #          - --remove-duplicate-keys
   #          - --remove-unused-variables
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.16.0
+    rev: v3.17.0
     hooks:
       - id: pyupgrade
-        args: [--py38-plus]
+        exclude: \.(po|pot)$
   - repo: https://github.com/PyCQA/isort
     rev: 5.13.2
     hooks:
       - id: isort
+        exclude: \.(po|pot)$
   - repo: https://github.com/psf/black
-    rev: 24.4.2
+    rev: 24.8.0
     hooks:
       - id: black
         args: [--safe, --quiet]
+        exclude: \.(po|pot)$
   - repo: https://github.com/Pierre-Sassoulas/black-disable-checker
     rev: v1.1.3
     hooks:
@@ -81,10 +85,12 @@ repos:
     hooks:
       - id: prettier
         args: [--prose-wrap=always, --print-width=88]
+        exclude: \.(po|pot)$
   - repo: https://github.com/DanielNoord/pydocstringformatter
     rev: v0.7.3
     hooks:
       - id: pydocstringformatter
+        exclude: \.(po|pot)$
         args:
           [
             --style=numpydoc,

.readthedocs.yml

@@ -4,7 +4,7 @@ formats: []
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.12"
 
 sphinx:
   configuration: docs/conf.py

README.rst

@@ -16,6 +16,9 @@ Pycord
 .. image:: https://img.shields.io/github/v/release/Pycord-Development/pycord?include_prereleases&label=Latest%20Release&logo=github&sort=semver&style=for-the-badge&logoColor=white
    :target: https://github.com/Pycord-Development/pycord/releases
    :alt: Latest release
+.. image:: https://badges.crowdin.net/badge/dark/crowdin-on-light.png
+   :target: https://crowdin.com/?utm_source=badge&utm_medium=referral&utm_campaign=badge-add-on
+   :alt: Crowdin | Agile localization for tech companies
 
 A fork of discord.py. Pycord is a modern, easy to use, feature-rich, and async ready API wrapper for Discord written in Python.
 
@@ -141,3 +144,9 @@ Useful Links
 - `Learn how to create Discord bots with Pycord <https://guide.pycord.dev>`_
 - `Our Official Discord Server <https://pycord.dev/discord>`_
 - `Official Discord Developers Server <https://discord.gg/discord-developers>`_
+
+Translations
+------------
+
+.. image:: https://badges.awesome-crowdin.com/translation-200034237-5.png
+   :alt: Translation Status

crowdin.yml

@@ -0,0 +1,19 @@
+base_path: "docs/build/locales"
+base_url: "https://pycord.crowdin.com"
+
+preserve_hierarchy: true
+
+commit_message: "docs: Update translations"
+
+export_languages: ["de", "ja", "fr", "it", "hi", "ko", "pt-BR", "es-ES", "zh-CN"]
+
+bundles:
+  - 4
+
+files:
+  [
+    {
+      source: "**/*.pot",
+      translation: "/docs/locales/%two_letters_code%/LC_MESSAGES/%original_path%/%file_name%.po",
+    },
+  ]

discord/audit_logs.py

@@ -213,7 +213,7 @@ class AuditLogDiff:
     def __len__(self) -> int:
         return len(self.__dict__)
 
-    def __iter__(self) -> Generator[tuple[str, Any], None, None]:
+    def __iter__(self) -> Generator[tuple[str, Any]]:
         yield from self.__dict__.items()
 
     def __repr__(self) -> str:

discord/bot.py

@@ -1051,7 +1051,7 @@ def inner(cls: type[SlashCommandGroup]) -> SlashCommandGroup:
 
     slash_group = group
 
-    def walk_application_commands(self) -> Generator[ApplicationCommand, None, None]:
+    def walk_application_commands(self) -> Generator[ApplicationCommand]:
         """An iterator that recursively walks through all application commands and subcommands.
 
         Yields

discord/client.py

@@ -1041,7 +1041,7 @@ def get_poll(self, id: int, /) -> Poll | None:
         """
         return self._connection.get_poll(id)
 
-    def get_all_channels(self) -> Generator[GuildChannel, None, None]:
+    def get_all_channels(self) -> Generator[GuildChannel]:
         """A generator that retrieves every :class:`.abc.GuildChannel` the client can 'access'.
 
         This is equivalent to: ::
@@ -1065,7 +1065,7 @@ def get_all_channels(self) -> Generator[GuildChannel, None, None]:
         for guild in self.guilds:
             yield from guild.channels
 
-    def get_all_members(self) -> Generator[Member, None, None]:
+    def get_all_members(self) -> Generator[Member]:
         """Returns a generator with every :class:`.Member` the client can see.
 
         This is equivalent to: ::

discord/cog.py

@@ -346,7 +346,7 @@ def description(self) -> str:
     def description(self, description: str) -> None:
         self.__cog_description__ = description
 
-    def walk_commands(self) -> Generator[ApplicationCommand, None, None]:
+    def walk_commands(self) -> Generator[ApplicationCommand]:
         """An iterator that recursively walks through this cog's commands and subcommands.
 
         Yields

discord/commands/core.py

@@ -1513,7 +1513,7 @@ async def call_after_hooks(self, ctx: ApplicationContext) -> None:
             else:
                 await self._after_invoke(ctx)  # type: ignore
 
-    def walk_commands(self) -> Generator[SlashCommand | SlashCommandGroup, None, None]:
+    def walk_commands(self) -> Generator[SlashCommand | SlashCommandGroup]:
         """An iterator that recursively walks through all slash commands and groups in this group.
 
         Yields

discord/ext/commands/cog.py

@@ -50,7 +50,7 @@ def __new__(cls: type[CogT], *args: Any, **kwargs: Any) -> CogT:
         # To do this, we need to interfere with the Cog creation process.
         return super().__new__(cls)
 
-    def walk_commands(self) -> Generator[Command, None, None]:
+    def walk_commands(self) -> Generator[Command]:
         """An iterator that recursively walks through this cog's commands and subcommands.
 
         Yields

discord/ext/commands/core.py

@@ -1326,7 +1326,7 @@ def remove_command(self, name: str) -> Command[CogT, Any, Any] | None:
                 self.prefixed_commands[alias] = cmd
         return command
 
-    def walk_commands(self) -> Generator[Command[CogT, Any, Any], None, None]:
+    def walk_commands(self) -> Generator[Command[CogT, Any, Any]]:
         """An iterator that recursively walks through all commands and subcommands.
 
         .. versionchanged:: 1.4

discord/oggparse.py

@@ -74,7 +74,7 @@ def __init__(self, stream: IO[bytes]) -> None:
         except Exception:
             raise OggError("bad data stream") from None
 
-    def iter_packets(self) -> Generator[tuple[bytes, bool], None, None]:
+    def iter_packets(self) -> Generator[tuple[bytes, bool]]:
         packetlen = offset = 0
         partial = True
 
@@ -106,13 +106,13 @@ def _next_page(self) -> OggPage | None:
         else:
             raise OggError("invalid header magic")
 
-    def _iter_pages(self) -> Generator[OggPage, None, None]:
+    def _iter_pages(self) -> Generator[OggPage]:
         page = self._next_page()
         while page:
             yield page
             page = self._next_page()
 
-    def iter_packets(self) -> Generator[bytes, None, None]:
+    def iter_packets(self) -> Generator[bytes]:
         partial = b""
         for page in self._iter_pages():
             for data, complete in page.iter_packets():