Skip to content

Commit 560a458

Browse files
bnbongbnbong
authored
Merge pull request #28 from bnbong/dev
[DOCS] Add docs translation script
2 parents 12a9fb2 + e39aaf1 commit 560a458

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+3647
-306
lines changed

‎.github/workflows/test.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@ jobs:
3131
- name: Setup PDM
3232
uses: pdm-project/setup-pdm@v4
3333

34+
- name: Install package managers for tests
35+
run: |
36+
pip install uv
37+
pip install poetry
38+
# PDM is already installed via setup-pdm action
39+
3440
- name: Install dependencies
3541
run: pdm install -G dev
3642

‎.github/workflows/translate-docs.yml‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
name: Translate Documentation
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
target_language:
7+
description: 'Target language code (e.g., ko, ja, zh). Leave empty for all languages.'
8+
required: false
9+
type: string
10+
api_provider:
11+
description: 'AI API provider for translation'
12+
required: true
13+
type: choice
14+
options:
15+
- openai
16+
- anthropic
17+
default: openai
18+
specific_files:
19+
description: 'Specific files to translate (space-separated, relative to docs/en/). Example: index.md user-guide/installation.md'
20+
required: false
21+
type: string
22+
create_pr:
23+
description: 'Create Pull Request for translations'
24+
required: true
25+
type: boolean
26+
default: true
27+
28+
# Trigger on new documentation commits (optional - uncomment to enable)
29+
# push:
30+
# branches:
31+
# - main
32+
# paths:
33+
# - 'docs/en/**/*.md' # Only trigger on English documentation changes
34+
35+
jobs:
36+
translate:
37+
runs-on: ubuntu-latest
38+
39+
permissions:
40+
contents: write
41+
pull-requests: write
42+
43+
steps:
44+
- name: Checkout repository
45+
uses: actions/checkout@v4
46+
with:
47+
fetch-depth: 0
48+
49+
- name: Set up Python
50+
uses: actions/setup-python@v5
51+
with:
52+
python-version: '3.12'
53+
54+
- name: Install dependencies
55+
run: |
56+
python -m pip install --upgrade pip
57+
pip install openai anthropic
58+
59+
- name: Configure Git
60+
run: |
61+
git config --global user.name "github-actions[bot]"
62+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
63+
64+
- name: Run translation
65+
env:
66+
TRANSLATION_API_KEY: ${{ secrets.TRANSLATION_API_KEY }}
67+
run: |
68+
ARGS="--api-provider ${{ inputs.api_provider }}"
69+
70+
if [ -n "${{ inputs.target_language }}" ]; then
71+
ARGS="$ARGS --target-lang ${{ inputs.target_language }}"
72+
fi
73+
74+
if [ -n "${{ inputs.specific_files }}" ]; then
75+
ARGS="$ARGS --files ${{ inputs.specific_files }}"
76+
fi
77+
78+
if [ "${{ inputs.create_pr }}" = "false" ]; then
79+
ARGS="$ARGS --no-pr"
80+
fi
81+
82+
python scripts/translate.py $ARGS
83+
84+
- name: Create Pull Request
85+
if: inputs.create_pr == true
86+
uses: peter-evans/create-pull-request@v6
87+
with:
88+
token: ${{ secrets.GITHUB_TOKEN }}
89+
commit-message: "docs: Add ${{ inputs.target_language || 'multi-language' }} translations"
90+
branch: translation/${{ inputs.target_language || 'auto' }}-${{ github.run_number }}
91+
delete-branch: true
92+
title: "[Translation] Add ${{ inputs.target_language || 'multi-language' }} documentation"
93+
body: |
94+
## Automated Translation
95+
96+
This PR contains automated translations for the documentation.
97+
98+
### Translation Details
99+
- **Target Language**: ${{ inputs.target_language || 'All configured languages' }}
100+
- **API Provider**: ${{ inputs.api_provider }}
101+
- **Trigger**: ${{ github.event_name }}
102+
- **Run ID**: ${{ github.run_id }}
103+
104+
### Review Checklist
105+
- [ ] Markdown formatting is preserved
106+
- [ ] Code blocks are unchanged
107+
- [ ] Technical terms are appropriate
108+
- [ ] Links work correctly
109+
- [ ] Grammar and spelling are correct
110+
111+
### Files Changed
112+
Please review the translated files for accuracy and consistency.
113+
114+
---
115+
*Generated by GitHub Actions*
116+
labels: |
117+
documentation
118+
translation
119+
automated

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,13 @@ coverage.xml
1515
coverage/
1616
temp/
1717

18+
# Translation and API keys
19+
.env
20+
.env.local
21+
*.key
22+
*_api_key.txt
23+
translation_cache/
24+
1825
.pdm-python
1926
### VisualStudioCode template
2027
.vscode/*

‎CONTRIBUTING.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,207 @@ For more detailed information about security requirements and project guidelines
380380
- [SECURITY.md](SECURITY.md) for security guidelines
381381
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for project principles
382382

383+
## Contributing Translations
384+
385+
FastAPI-fastkit documentation supports multiple languages. Contributing translations helps users worldwide.
386+
387+
### Supported Languages
388+
389+
- 🇬🇧 English (en) - Default
390+
- 🇰🇷 Korean (ko)
391+
- 🇯🇵 Japanese (ja)
392+
- 🇨🇳 Chinese (zh)
393+
- 🇪🇸 Spanish (es)
394+
- 🇫🇷 French (fr)
395+
- 🇩🇪 German (de)
396+
397+
### Translation Setup
398+
399+
#### 1. Install Dependencies
400+
401+
```bash
402+
pdm install -G docs -G translation
403+
# Or: pip install mkdocs mkdocs-material mkdocs-static-i18n openai anthropic
404+
```
405+
406+
#### 2. Set Up API Key
407+
408+
Get an API key from OpenAI or Anthropic and set it as an environment variable:
409+
410+
```bash
411+
export TRANSLATION_API_KEY="your-api-key-here"
412+
```
413+
414+
#### 3. First-Time Setup (Maintainers Only)
415+
416+
If this is the first time setting up the i18n structure:
417+
418+
```bash
419+
./scripts/setup-i18n-structure.sh
420+
```
421+
422+
This migrates existing English docs to `docs/en/` and creates language directories.
423+
424+
### Translating Documentation
425+
426+
#### Translate to Specific Language
427+
428+
```bash
429+
# Translate all docs to Korean
430+
python scripts/translate.py --target-lang ko --api-provider openai
431+
432+
# Translate specific files (paths relative to docs/en/)
433+
python scripts/translate.py --target-lang ko --files index.md user-guide/installation.md --api-provider openai
434+
435+
# Translate without creating PR (for local testing)
436+
python scripts/translate.py --target-lang ko --no-pr --api-provider openai
437+
```
438+
439+
#### Using GitHub Actions
440+
441+
1. Go to repository → Actions → "Translate Documentation"
442+
2. Click "Run workflow"
443+
3. Select target language and options
444+
4. Wait for automated PR to be created
445+
5. Review and merge the translation
446+
447+
### Translation Workflow
448+
449+
1. **Write English documentation** in `docs/en/`
450+
2. **Test locally**: `mkdocs serve`
451+
3. **Commit English version** to main branch
452+
4. **Run translation script** or trigger GitHub Actions
453+
5. **Review PR**: Check formatting, technical terms, links
454+
6. **Merge** and deploy
455+
456+
### Translation Quality Guidelines
457+
458+
When reviewing translations:
459+
460+
- ✅ Markdown formatting is preserved
461+
- ✅ Code blocks are unchanged
462+
- ✅ Technical terms are appropriate
463+
- ✅ Links work correctly
464+
- ✅ Grammar and spelling are correct
465+
466+
### Manual Translation
467+
468+
You can also translate manually:
469+
470+
1. Copy file from `docs/en/` to `docs/{lang}/`
471+
2. Translate the content
472+
3. Create PR with `[DOCS]` tag
473+
474+
### Adding New Languages
475+
476+
To add support for a new language:
477+
478+
1. **Update `scripts/translation_config.json`**:
479+
```json
480+
{
481+
"code": "pt",
482+
"name": "Portuguese",
483+
"native_name": "Português",
484+
"enabled": true
485+
}
486+
```
487+
488+
2. **Update `mkdocs.yml`**:
489+
```yaml
490+
- locale: pt
491+
name: Português
492+
build: true
493+
```
494+
495+
3. **Run translation**:
496+
```bash
497+
python scripts/translate.py --target-lang pt
498+
```
499+
500+
### Translation System Architecture
501+
502+
**Core Components:**
503+
504+
- **`scripts/translate.py`**: AI-powered translation script
505+
- Supports OpenAI GPT-4 and Anthropic Claude
506+
- Preserves markdown formatting and code blocks
507+
- Creates GitHub PRs automatically
508+
509+
- **`scripts/setup-i18n-structure.sh`**: Migration tool
510+
- Moves docs to language-specific directories
511+
- Creates symbolic links for shared assets
512+
513+
- **`scripts/translation_config.json`**: Configuration
514+
- Language settings
515+
- Translation options
516+
- Quality check parameters
517+
518+
- **`.github/workflows/translate-docs.yml`**: GitHub Actions workflow
519+
- Automated translation on trigger
520+
- Manual workflow dispatch
521+
522+
**Directory Structure:**
523+
524+
```
525+
docs/
526+
├── en/ # English (source)
527+
├── ko/ # Korean
528+
├── ja/ # Japanese
529+
├── zh/ # Chinese
530+
├── es/ # Spanish
531+
├── fr/ # French
532+
├── de/ # German
533+
├── css/ # Shared assets
534+
├── js/
535+
└── img/
536+
```
537+
538+
### Troubleshooting
539+
540+
**Import Error:**
541+
```bash
542+
pip install openai anthropic
543+
```
544+
545+
**API Key Error:**
546+
```bash
547+
export TRANSLATION_API_KEY="your-key"
548+
```
549+
550+
**Build Fails:**
551+
```bash
552+
# Ensure docs are in language directories
553+
ls -la docs/en/index.md
554+
```
555+
556+
For detailed translation guidelines, see [Translation Guide](docs/en/contributing/translation-guide.md).
557+
558+
### Updating Navigation Translations
559+
560+
When you add new documentation pages, update navigation translations:
561+
562+
**Option 1: Automatic Update (Recommended)**
563+
564+
```bash
565+
# Update all language nav translations automatically
566+
python scripts/update_nav_translations.py
567+
568+
# With AI translation for missing items
569+
python scripts/update_nav_translations.py --api-key "your-key"
570+
```
571+
572+
**Option 2: Manual Update**
573+
574+
Edit `mkdocs.yml` and add translations for each language under `nav_translations`:
575+
576+
```yaml
577+
- locale: ko
578+
nav_translations:
579+
New Page Title: 새로운 페이지 제목
580+
```
581+
582+
**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.
583+
383584
## Additional note
384585
385586
If you look at source codes, you will see a commentary at the top of the module that describes about the module.

‎docs/de/.gitkeep‎

Whitespace-only changes.

‎docs/de/css‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../css

‎docs/de/img‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../img

‎docs/de/js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../js

‎docs/en/.gitkeep‎

Whitespace-only changes.

‎docs/changelog.md‎ renamed to ‎docs/en/changelog.md‎

File renamed without changes.

0 commit comments

Comments
 (0)