i18n Crowdin integration (#880)

.github/workflows/copy-workflow.yml

@@ -0,0 +1,74 @@
+name: Crowdin Copy and Create PR
+
+on:
+  workflow_dispatch:
+  # push:
+  #   paths: [ 'docs/**', 'platforms/**','i18n/en/**', 'src/pages/**', 'meeting-notes/**' ]
+  #   branches: [ main ]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  crowdin_copy_and_pr:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Merge latest changes from origin/main
+        run: |
+          git fetch origin
+          git checkout main
+          git merge origin/main
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Run crowdin:fix
+        run: yarn run crowdin:fix
+
+      - name: Configure Git
+        run: |
+          git config --global user.name 'github-actions'
+          git config --global user.email '[email protected]'
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet; then
+            echo "changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create and push changes to branch
+        if: steps.changes.outputs.changes == 'true'
+        run: |
+          BRANCH_NAME="crowdin-copy-changes"
+          git push origin --delete $BRANCH_NAME || true
+          git checkout -b $BRANCH_NAME
+          git add .
+          git commit -m "chore: Copy ignored files using crowdin:fix"
+          git push --force --set-upstream origin $BRANCH_NAME
+          echo "branch_name=$BRANCH_NAME" >> $GITHUB_ENV
+
+      - name: Install GitHub CLI
+        if: steps.changes.outputs.changes == 'true'
+        run: sudo apt-get install -y gh
+
+      - name: Create Pull Request
+        if: steps.changes.outputs.changes == 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh pr create --repo ${{ github.repository }} --base main --head ${{ env.branch_name }} --title "Copy ignored files using crowdin:fix" --body "This PR was created by GitHub Actions to copy ignored files using the crowdin:fix command."

.github/workflows/download-workflow.yml

@@ -0,0 +1,37 @@
+name: Crowdin Download Action
+
+on:
+  workflow_dispatch:
+  ### Schedule currently disabled ###
+  # schedule:
+  #   - cron: '0 9 * * *'
+  #   - cron: '0 13 * * *'
+  #   - cron: '0 17 * * *'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  crowdin:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Synchronize with Crowdin
+        uses: crowdin/github-action@v2
+        with:
+          upload_sources: false
+          upload_translations: false
+          download_translations: true
+          localization_branch_name: l10n_crowdin_translations
+
+          create_pull_request: true
+          pull_request_title: 'New Crowdin translations'
+          pull_request_body: 'New Crowdin pull request with translations'
+          pull_request_base_branch_name: 'main'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CROWDIN_PROJECT_ID: '669532'
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

.github/workflows/main.yml

@@ -32,6 +32,6 @@ jobs:
         run: yarn check:mdx
 
       - name: Build app
-        run: yarn build
+        run: yarn build --locale en
 
 

.github/workflows/upload-workflow.yml

@@ -0,0 +1,36 @@
+name: Crowdin Upload
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+
+jobs:
+  crowdin-upload:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Docs Repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+          cache-dependency-path: '**/yarn.lock'
+
+      - name: Install Dependencies
+        run: yarn --prefer-offline
+
+      - name: Write Translations
+        run: yarn write-translations
+
+      - name: Crowdin push
+        uses: crowdin/github-action@v2
+        with:
+          upload_sources: true
+          upload_translations: false
+          download_translations: false
+        env:
+          CROWDIN_PROJECT_ID: '669532'
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

.gitignore

@@ -26,4 +26,9 @@ yarn-error.log*
 # non-production openrpc.json files
 /openrpc/*openrpc.json
 
+# Environment variables
+.env
+
+# translation files
+i18n
 stellar-cli-repo

Dockerfile

@@ -15,10 +15,18 @@ RUN apt-get update && apt-get install --no-install-recommends -y gpg curl git ma
     apt-get update && apt-get install -y nodejs yarn && apt-get clean
 
 COPY . /app/
+ARG CROWDIN_PERSONAL_TOKEN
 
 RUN yarn install
 RUN yarn rpcspec:build
 RUN yarn stellar-cli:build
+# TODO: This takes a bit of time, we should probably make sure it's only done
+# for production builds
+# See: https://docusaurus.io/docs/3.4.0/i18n/crowdin#automate-with-ci
+RUN CROWDIN_PERSONAL_TOKEN=${CROWDIN_PERSONAL_TOKEN} yarn crowdin:sync
+RUN yarn crowdin:fix
+# TODO: It's actually this part that is more time-consuming. The best way to
+# speed this up is to generate the preview for only `--locale en`
 RUN NODE_OPTIONS="--max-old-space-size=4096" yarn build
 
 FROM nginx:1.27

Makefile

@@ -9,7 +9,7 @@ TAG ?= stellar/stellar-docs:$(LABEL)
 BUILD_DATE := $(shell date -u +%FT%TZ)
 
 docker-build:
-	$(SUDO) docker build --no-cache --pull --label org.opencontainers.image.created="$(BUILD_DATE)" -t $(TAG) .
+	$(SUDO) docker build --no-cache --pull --label org.opencontainers.image.created="$(BUILD_DATE)" -t $(TAG) . --build-arg CROWDIN_PERSONAL_TOKEN=${CROWDIN_PERSONAL_TOKEN}
 
 docker-push:
 	$(SUDO) docker push $(TAG)

config/anchorPlatform.config.ts

@@ -1,5 +1,7 @@
 import type { PluginConfig } from '@docusaurus/types';
 import versions from '../ap_versions.json'
+import { makeEditUrl } from './constants';
+
 import type * as Plugin from '@docusaurus/types/src/plugin';
 import type * as OpenApiPlugin from 'docusaurus-plugin-openapi-docs';
 import type { APIVersionOptions } from 'docusaurus-plugin-openapi-docs/src/types';
@@ -54,7 +56,7 @@ export const anchorPlatformPluginInstances: PluginConfig[] = [
             routeBasePath: "/platforms/anchor-platform",
             docItemComponent: "@theme/ApiItem",
             sidebarPath: "config/anchorPlatform.sidebar.ts",
-            editUrl: "https://github.com/stellar/stellar-docs/tree/main",
+            editUrl: makeEditUrl,
             exclude: ['**/component/**', '**/README.md'],
             showLastUpdateTime: true,
             showLastUpdateAuthor: true,

config/constants.ts

@@ -0,0 +1,11 @@
+export const DEFAULT_LOCALE: string = 'en';
+export const LOCALE_FULL_CODE: Record<string, string> = {
+  es: 'es-ES',
+};
+
+export const makeEditUrl = ({ locale, versionDocsDirPath, docPath }) => {
+  if (locale !== DEFAULT_LOCALE) {
+    return `https://crowdin.com/project/stellar-dev-docs/${LOCALE_FULL_CODE[locale]}`
+  }
+  return `https://github.com/stellar/stellar-docs/edit/main/${versionDocsDirPath}/${docPath}`
+};

config/disbursementPlatform.config.ts

@@ -1,3 +1,5 @@
+import { makeEditUrl } from './constants';
+
 import type { PluginConfig } from '@docusaurus/types';
 import type * as Plugin from '@docusaurus/types/src/plugin';
 import type * as OpenApiPlugin from 'docusaurus-plugin-openapi-docs';
@@ -29,7 +31,7 @@ export const disbursementPlatformPluginInstances: PluginConfig[] = [
             routeBasePath: "/platforms/stellar-disbursement-platform",
             docItemComponent: "@theme/ApiItem",
             sidebarPath: "config/disbursementPlatform.sidebar.ts",
-            editUrl: "https://github.com/stellar/stellar-docs/tree/main",
+            editUrl: makeEditUrl,
             exclude: ['**/component/**', '**/README.md'],
             showLastUpdateTime: true,
             showLastUpdateAuthor: true,

crowdin.yaml

@@ -0,0 +1,37 @@
+# Crowdin credentials
+project_id: '669532'
+api_token_env: CROWDIN_PERSONAL_TOKEN
+
+# Choose file structure in Crowdin
+# e.g. true or false
+preserve_hierarchy: true
+
+# Files configuration
+files:
+  # JSON translation files
+  - source: /i18n/en/**/*
+    translation: /i18n/%two_letters_code%/**/%original_file_name%
+  # Docs Markdown files
+  - source: /docs/**/*
+    translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
+    ignore : ['**/*.api.mdx', '**/*.info.mdx', '**/*.tag.mdx', '**/*.schema.mdx', '**/*.json']
+  # Stellar Disbursement Platform Docs Markdown files
+  - source: /platforms/stellar-disbursement-platform/**/*
+    translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs-sdp/current/**/%original_file_name%
+    ignore : ['**/*.api.mdx', '**/*.info.mdx', '**/*.tag.mdx', '**/*.schema.mdx', '**/*.json']
+  # Anchor Platform Docs Markdown files
+  - source: /platforms/anchor-platform/**/*
+    translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs-ap/current/**/%original_file_name%
+    ignore : ['**/*.api.mdx', '**/*.info.mdx', '**/*.tag.mdx', '**/*.schema.mdx', '**/*.json']
+  # Anchor Platform versioned docs
+  - source: /ap_versioned_docs/**/*
+    translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs-ap/**/%original_file_name%
+    ignore : ['**/*.api.mdx', '**/*.info.mdx', '**/*.tag.mdx', '**/*.schema.mdx', '**/*.json']
+  # Meeting Notes Blog Markdown files
+  - source: /meeting-notes/**/*
+    translation: /i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%
+  # Pages Markdown files
+  - source: /src/pages/**/*
+    translation: /i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%
+    ignore: ['**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx', '**/*.css']
+    type: 'mdx_v2'

docs/README.mdx

@@ -6,30 +6,30 @@ hide_table_of_contents: true
 
 ## Navigating the docs
 
-### [Build](/docs/build/README.mdx)
+### [Build](./build/README.mdx)
 
 Contains tutorials and how-to guides for writing smart contracts, building applications, interacting with the network, and more.
 
-### [Learn](/docs/learn/fundamentals/README.mdx)
+### [Learn](./learn/fundamentals/README.mdx)
 
 Find all informational and conceptual content here. Learn about Stellar fundamentals like how accounts and transactions function, dive deeper into the functionality of each operation, discover how fees work, and more.
 
-### [Tokens](/docs/tokens/README.mdx)
+### [Tokens](./tokens/README.mdx)
 
 Information on how to issue assets on the Stellar network and create custom smart contract tokens.
 
-### [Data](/docs/data/README.mdx)
+### [Data](./data/README.mdx)
 
 Discover various data availability options: RPC, Hubble, and Horizon.
 
-### [Tools](/docs/tools/README.mdx)
+### [Tools](./tools/README.mdx)
 
 Learn about all the available tools at your disposal for building on, interacting with, or just watching the Stellar network. Also, find information on how to use the Anchor Platform or Stellar Disbursement Platform.
 
-### [Networks](/docs/networks/README.mdx)
+### [Networks](./networks/README.mdx)
 
 Information about deployed networks (Mainnet, Testnet, and Futurenet), current software versions, and resource limitations and fees.
 
-### [Validators](/docs/validators/README.mdx)
+### [Validators](./validators/README.mdx)
 
 Everything you'll need to know if you want to run, operate, and maintain a core validator node on the Stellar network.

docs/build/apps/dapp-frontend.mdx

@@ -164,7 +164,7 @@ Let's see it in action! Start the dev server:
 npm run dev
 ```
 
-And open [http://localhost:4321](http://localhost:4321) in your browser. You should see the greeting from the contract!
+And open [localhost:4321](http://localhost:4321) in your browser. You should see the greeting from the contract!
 
 You can try updating the `{ to: 'Soroban' }` argument. When you save the file, the page will automatically update.