[DOCS] Add docs translation script

.github/workflows/test.yml

@@ -31,6 +31,12 @@ jobs:
       - name: Setup PDM
         uses: pdm-project/setup-pdm@v4
 
+      - name: Install package managers for tests
+        run: |
+          pip install uv
+          pip install poetry
+          # PDM is already installed via setup-pdm action
+
       - name: Install dependencies
         run: pdm install -G dev
 

.github/workflows/translate-docs.yml

@@ -0,0 +1,119 @@
+name: Translate Documentation
+
+on:
+  workflow_dispatch:
+    inputs:
+      target_language:
+        description: 'Target language code (e.g., ko, ja, zh). Leave empty for all languages.'
+        required: false
+        type: string
+      api_provider:
+        description: 'AI API provider for translation'
+        required: true
+        type: choice
+        options:
+          - openai
+          - anthropic
+        default: openai
+      specific_files:
+        description: 'Specific files to translate (space-separated, relative to docs/en/). Example: index.md user-guide/installation.md'
+        required: false
+        type: string
+      create_pr:
+        description: 'Create Pull Request for translations'
+        required: true
+        type: boolean
+        default: true
+
+  # Trigger on new documentation commits (optional - uncomment to enable)
+  # push:
+  #   branches:
+  #     - main
+  #   paths:
+  #     - 'docs/en/**/*.md'  # Only trigger on English documentation changes
+
+jobs:
+  translate:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install openai anthropic
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Run translation
+        env:
+          TRANSLATION_API_KEY: ${{ secrets.TRANSLATION_API_KEY }}
+        run: |
+          ARGS="--api-provider ${{ inputs.api_provider }}"
+
+          if [ -n "${{ inputs.target_language }}" ]; then
+            ARGS="$ARGS --target-lang ${{ inputs.target_language }}"
+          fi
+
+          if [ -n "${{ inputs.specific_files }}" ]; then
+            ARGS="$ARGS --files ${{ inputs.specific_files }}"
+          fi
+
+          if [ "${{ inputs.create_pr }}" = "false" ]; then
+            ARGS="$ARGS --no-pr"
+          fi
+
+          python scripts/translate.py $ARGS
+
+      - name: Create Pull Request
+        if: inputs.create_pr == true
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "docs: Add ${{ inputs.target_language || 'multi-language' }} translations"
+          branch: translation/${{ inputs.target_language || 'auto' }}-${{ github.run_number }}
+          delete-branch: true
+          title: "[Translation] Add ${{ inputs.target_language || 'multi-language' }} documentation"
+          body: |
+            ## Automated Translation
+
+            This PR contains automated translations for the documentation.
+
+            ### Translation Details
+            - **Target Language**: ${{ inputs.target_language || 'All configured languages' }}
+            - **API Provider**: ${{ inputs.api_provider }}
+            - **Trigger**: ${{ github.event_name }}
+            - **Run ID**: ${{ github.run_id }}
+
+            ### Review Checklist
+            - [ ] Markdown formatting is preserved
+            - [ ] Code blocks are unchanged
+            - [ ] Technical terms are appropriate
+            - [ ] Links work correctly
+            - [ ] Grammar and spelling are correct
+
+            ### Files Changed
+            Please review the translated files for accuracy and consistency.
+
+            ---
+            *Generated by GitHub Actions*
+          labels: |
+            documentation
+            translation
+            automated

.gitignore

@@ -15,6 +15,13 @@ coverage.xml
 coverage/
 temp/
 
+# Translation and API keys
+.env
+.env.local
+*.key
+*_api_key.txt
+translation_cache/
+
 .pdm-python
 ### VisualStudioCode template
 .vscode/*

CONTRIBUTING.md

@@ -380,6 +380,207 @@ For more detailed information about security requirements and project guidelines
 - [SECURITY.md](SECURITY.md) for security guidelines
 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for project principles
 
+## Contributing Translations
+
+FastAPI-fastkit documentation supports multiple languages. Contributing translations helps users worldwide.
+
+### Supported Languages
+
+- 🇬🇧 English (en) - Default
+- 🇰🇷 Korean (ko)
+- 🇯🇵 Japanese (ja)
+- 🇨🇳 Chinese (zh)
+- 🇪🇸 Spanish (es)
+- 🇫🇷 French (fr)
+- 🇩🇪 German (de)
+
+### Translation Setup
+
+#### 1. Install Dependencies
+
+```bash
+pdm install -G docs -G translation
+# Or: pip install mkdocs mkdocs-material mkdocs-static-i18n openai anthropic
+```
+
+#### 2. Set Up API Key
+
+Get an API key from OpenAI or Anthropic and set it as an environment variable:
+
+```bash
+export TRANSLATION_API_KEY="your-api-key-here"
+```
+
+#### 3. First-Time Setup (Maintainers Only)
+
+If this is the first time setting up the i18n structure:
+
+```bash
+./scripts/setup-i18n-structure.sh
+```
+
+This migrates existing English docs to `docs/en/` and creates language directories.
+
+### Translating Documentation
+
+#### Translate to Specific Language
+
+```bash
+# Translate all docs to Korean
+python scripts/translate.py --target-lang ko --api-provider openai
+
+# Translate specific files (paths relative to docs/en/)
+python scripts/translate.py --target-lang ko --files index.md user-guide/installation.md --api-provider openai
+
+# Translate without creating PR (for local testing)
+python scripts/translate.py --target-lang ko --no-pr --api-provider openai
+```
+
+#### Using GitHub Actions
+
+1. Go to repository → Actions → "Translate Documentation"
+2. Click "Run workflow"
+3. Select target language and options
+4. Wait for automated PR to be created
+5. Review and merge the translation
+
+### Translation Workflow
+
+1. **Write English documentation** in `docs/en/`
+2. **Test locally**: `mkdocs serve`
+3. **Commit English version** to main branch
+4. **Run translation script** or trigger GitHub Actions
+5. **Review PR**: Check formatting, technical terms, links
+6. **Merge** and deploy
+
+### Translation Quality Guidelines
+
+When reviewing translations:
+
+- ✅ Markdown formatting is preserved
+- ✅ Code blocks are unchanged
+- ✅ Technical terms are appropriate
+- ✅ Links work correctly
+- ✅ Grammar and spelling are correct
+
+### Manual Translation
+
+You can also translate manually:
+
+1. Copy file from `docs/en/` to `docs/{lang}/`
+2. Translate the content
+3. Create PR with `[DOCS]` tag
+
+### Adding New Languages
+
+To add support for a new language:
+
+1. **Update `scripts/translation_config.json`**:
+```json
+{
+  "code": "pt",
+  "name": "Portuguese",
+  "native_name": "Português",
+  "enabled": true
+}
+```
+
+2. **Update `mkdocs.yml`**:
+```yaml
+- locale: pt
+  name: Português
+  build: true
+```
+
+3. **Run translation**:
+```bash
+python scripts/translate.py --target-lang pt
+```
+
+### Translation System Architecture
+
+**Core Components:**
+
+- **`scripts/translate.py`**: AI-powered translation script
+  - Supports OpenAI GPT-4 and Anthropic Claude
+  - Preserves markdown formatting and code blocks
+  - Creates GitHub PRs automatically
+
+- **`scripts/setup-i18n-structure.sh`**: Migration tool
+  - Moves docs to language-specific directories
+  - Creates symbolic links for shared assets
+
+- **`scripts/translation_config.json`**: Configuration
+  - Language settings
+  - Translation options
+  - Quality check parameters
+
+- **`.github/workflows/translate-docs.yml`**: GitHub Actions workflow
+  - Automated translation on trigger
+  - Manual workflow dispatch
+
+**Directory Structure:**
+
+```
+docs/
+├── en/                    # English (source)
+├── ko/                    # Korean
+├── ja/                    # Japanese
+├── zh/                    # Chinese
+├── es/                    # Spanish
+├── fr/                    # French
+├── de/                    # German
+├── css/                   # Shared assets
+├── js/
+└── img/
+```
+
+### Troubleshooting
+
+**Import Error:**
+```bash
+pip install openai anthropic
+```
+
+**API Key Error:**
+```bash
+export TRANSLATION_API_KEY="your-key"
+```
+
+**Build Fails:**
+```bash
+# Ensure docs are in language directories
+ls -la docs/en/index.md
+```
+
+For detailed translation guidelines, see [Translation Guide](docs/en/contributing/translation-guide.md).
+
+### Updating Navigation Translations
+
+When you add new documentation pages, update navigation translations:
+
+**Option 1: Automatic Update (Recommended)**
+
+```bash
+# Update all language nav translations automatically
+python scripts/update_nav_translations.py
+
+# With AI translation for missing items
+python scripts/update_nav_translations.py --api-key "your-key"
+```
+
+**Option 2: Manual Update**
+
+Edit `mkdocs.yml` and add translations for each language under `nav_translations`:
+
+```yaml
+- locale: ko
+  nav_translations:
+    New Page Title: 새로운 페이지 제목
+```
+
+**Note:** Korean translations should be kept complete. Other languages use basic translations (Home, User Guide, Tutorial, etc.). Native speakers can contribute more detailed translations via PR.
+
 ## Additional note
 
 If you look at source codes, you will see a commentary at the top of the module that describes about the module.

docs/de/css

@@ -0,0 +1 @@
+../css

docs/de/img

@@ -0,0 +1 @@
+../img

docs/de/js

@@ -0,0 +1 @@
+../js