Skip to content

Commit 4a2cebb

Browse files
lktron00lktron00
committed
docs(i18n): translate core READMEs to zh-CN, es, ja, pt-BR
Make the project approachable from the four largest non-English developer communities. Each translation is a sibling file to its English source, with a compact language-selector banner at the top so readers can jump between languages from any page. Ten English sources were chosen — the docs a newcomer actually reads before deciding whether to adopt the protocol: - README.md (root) - CONTRIBUTING.md - docs/QUICKSTART.md - docs/OBSERVABILITY.md - spec/README.md - sdks/{typescript,python,rust,go,wasm}/README.md That's 10 sources × 4 languages = 40 new translation files. The SDK READMEs also serve as the published description on npm, PyPI, crates.io, and pkg.go.dev, so non-English developers find the project even without visiting GitHub. Translation guarantees: - Code blocks, package names, URLs, protocol/algorithm names, env vars, and CLI flags are verbatim. - Consistent technical terminology across all 10 files per language. - Same Markdown structure and heading hierarchy as the English source. Also adds .github/workflows/i18n-sync.yml: a warn-only PR check that flags when an English source is modified but its translations aren't. Stale translations confuse non-English readers more than missing ones; this makes the drift visible without blocking merges. WASM translations are tracked; other translations (playground, specs, integration READMEs, scaffolder templates) remain English-only for now to keep the maintenance surface manageable.
1 parent 62e3154 commit 4a2cebb

51 files changed

Lines changed: 10266 additions & 0 deletions

Some content is hidden

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

‎.github/workflows/i18n-sync.yml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
name: i18n sync check
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "README.md"
7+
- "CONTRIBUTING.md"
8+
- "docs/QUICKSTART.md"
9+
- "docs/OBSERVABILITY.md"
10+
- "spec/README.md"
11+
- "sdks/typescript/README.md"
12+
- "sdks/python/README.md"
13+
- "sdks/rust/README.md"
14+
- "sdks/go/README.md"
15+
- "sdks/wasm/README.md"
16+
17+
permissions:
18+
contents: read
19+
pull-requests: write
20+
21+
jobs:
22+
check-translations-touched:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Check out PR head
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Warn when translations lag behind the English source
31+
shell: bash
32+
run: |
33+
set -euo pipefail
34+
base="${{ github.event.pull_request.base.sha }}"
35+
head="${{ github.event.pull_request.head.sha }}"
36+
37+
# Canonical set of (english source, translation directory siblings).
38+
# Keep LANGS in sync with the selector banner in each README.
39+
LANGS=(zh-CN es ja pt-BR)
40+
SOURCES=(
41+
"README.md"
42+
"CONTRIBUTING.md"
43+
"docs/QUICKSTART.md"
44+
"docs/OBSERVABILITY.md"
45+
"spec/README.md"
46+
"sdks/typescript/README.md"
47+
"sdks/python/README.md"
48+
"sdks/rust/README.md"
49+
"sdks/go/README.md"
50+
"sdks/wasm/README.md"
51+
)
52+
53+
# Files actually changed in this PR.
54+
mapfile -t changed < <(git diff --name-only "$base" "$head")
55+
56+
missing=()
57+
for src in "${SOURCES[@]}"; do
58+
# Did the English source change?
59+
touched=0
60+
for f in "${changed[@]}"; do
61+
if [[ "$f" == "$src" ]]; then touched=1; break; fi
62+
done
63+
[[ $touched -eq 0 ]] && continue
64+
65+
# For every language, the sibling translation must also be touched.
66+
dir=$(dirname "$src")
67+
base_name=$(basename "$src" .md)
68+
for lang in "${LANGS[@]}"; do
69+
tr="$dir/$base_name.$lang.md"
70+
tr_touched=0
71+
for f in "${changed[@]}"; do
72+
if [[ "$f" == "$tr" ]]; then tr_touched=1; break; fi
73+
done
74+
if [[ $tr_touched -eq 0 ]]; then
75+
missing+=("$tr (source changed: $src)")
76+
fi
77+
done
78+
done
79+
80+
if [[ ${#missing[@]} -eq 0 ]]; then
81+
echo "All translations updated alongside their English sources."
82+
exit 0
83+
fi
84+
85+
{
86+
echo ""
87+
echo "### Translations out of sync"
88+
echo ""
89+
echo "The following English sources changed in this PR but their translations were not updated:"
90+
echo ""
91+
for m in "${missing[@]}"; do
92+
echo "- \`$m\`"
93+
done
94+
echo ""
95+
echo "This is a warning, not a blocker. Please update the translations when you can — stale translations confuse non-English readers more than missing ones. The language set is currently: ${LANGS[*]}."
96+
} >> "$GITHUB_STEP_SUMMARY"
97+
98+
echo "::warning::One or more translations lag behind the English source — see job summary."

‎CONTRIBUTING.es.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
<sub>[English](CONTRIBUTING.md) · [中文](CONTRIBUTING.zh-CN.md) · **Español** · [日本語](CONTRIBUTING.ja.md) · [Português](CONTRIBUTING.pt-BR.md)</sub>
2+
3+
# Contribuir a DCP-AI
4+
5+
Gracias por tu interés en contribuir al Digital Citizenship Protocol for AI Agents. Esta guía te ayudará a empezar.
6+
7+
## Configuración del Entorno de Desarrollo
8+
9+
### Prerrequisitos
10+
11+
- **Node.js** >= 18 (requerido para el protocolo core y el SDK TypeScript)
12+
- **Python** >= 3.12 (requerido para el SDK Python)
13+
- **Go** >= 1.21 (requerido para el SDK Go)
14+
- **Rust** (toolchain stable, requerido para el SDK Rust)
15+
- **Git**
16+
17+
### Primeros Pasos
18+
19+
```bash
20+
# Clone the repository
21+
git clone https://github.com/dcp-ai-protocol/dcp-ai.git
22+
cd dcp-ai
23+
24+
# Install root dependencies (core protocol + CLI)
25+
npm install
26+
27+
# Run conformance tests to verify your setup (should print "DCP-AI CONFORMANCE PASS (V1 + V2)")
28+
npm run conformance
29+
```
30+
31+
### Setup de los SDKs
32+
33+
Cada SDK vive en su propio directorio bajo `sdks/` y tiene dependencias independientes:
34+
35+
```bash
36+
# TypeScript SDK
37+
cd sdks/typescript && npm install
38+
39+
# Python SDK
40+
cd sdks/python && pip install -e ".[dev]"
41+
42+
# Go SDK
43+
cd sdks/go && go mod download
44+
45+
# Rust SDK
46+
cd sdks/rust && cargo build
47+
48+
# WASM SDK (requires Rust + wasm-pack + Node.js)
49+
cd sdks/wasm && npm install
50+
```
51+
52+
## Ejecutar Tests
53+
54+
### Protocolo Core
55+
56+
```bash
57+
npm run conformance
58+
```
59+
60+
### SDKs
61+
62+
```bash
63+
# TypeScript
64+
cd sdks/typescript
65+
npm run test # Run tests
66+
npm run test:coverage # Run tests with coverage
67+
68+
# Python
69+
cd sdks/python
70+
pytest -v
71+
72+
# Go
73+
cd sdks/go
74+
go test ./...
75+
76+
# Rust
77+
cd sdks/rust
78+
cargo test
79+
80+
# WASM (build verification)
81+
cd sdks/wasm
82+
npm test
83+
```
84+
85+
## Estilo de Código
86+
87+
Este proyecto usa herramientas automatizadas para aplicar un estilo de código consistente:
88+
89+
- **ESLint** para linting de JavaScript/TypeScript (consulta `.eslintrc.json`)
90+
- **Prettier** para formateo de código (consulta `.prettierrc.json`)
91+
- **EditorConfig** para configuraciones básicas del editor (consulta `.editorconfig`)
92+
93+
### Reglas Clave
94+
95+
- Usa `const` por defecto; nunca uses `var`
96+
- Usa comillas simples para strings
97+
- Incluye siempre comas finales (trailing commas)
98+
- Ancho máximo de línea de 100 caracteres
99+
- Usa indentación de 2 espacios (excepto Makefiles)
100+
101+
Formatea tu código antes de hacer commit:
102+
103+
```bash
104+
npx prettier --write .
105+
npx eslint --fix .
106+
```
107+
108+
## Enviar Pull Requests
109+
110+
1. **Haz fork del repositorio** y crea una rama de feature desde `main`.
111+
2. **Haz tus cambios** en commits enfocados y lógicos.
112+
3. **Escribe o actualiza tests** para cualquier funcionalidad nueva o corrección de bugs.
113+
4. **Asegúrate de que todos los tests pasen** localmente antes de abrir un PR.
114+
5. **Abre un pull request** contra `main` con una descripción clara de qué cambió y por qué.
115+
116+
### Checklist del PR
117+
118+
- [ ] Todos los tests existentes pasan
119+
- [ ] Se agregaron nuevos tests para la funcionalidad nueva
120+
- [ ] El código sigue las pautas de estilo del proyecto
121+
- [ ] Documentación actualizada si aplica
122+
- [ ] Los mensajes de commit siguen el formato a continuación
123+
124+
## Formato de Mensajes de Commit
125+
126+
Usa mensajes de commit convencionales:
127+
128+
```
129+
<type>(<scope>): <short summary>
130+
131+
<optional body>
132+
```
133+
134+
### Tipos
135+
136+
- **feat**: Una nueva funcionalidad
137+
- **fix**: Una corrección de bug
138+
- **docs**: Cambios solo de documentación
139+
- **style**: Formateo, punto y coma faltantes, etc. (sin cambio de código)
140+
- **refactor**: Cambio de código que ni corrige un bug ni agrega una funcionalidad
141+
- **test**: Agregar o actualizar tests
142+
- **chore**: Proceso de build, actualizaciones de dependencias, tooling
143+
144+
### Scopes
145+
146+
- **core**: Protocolo core, CLI, schemas
147+
- **sdk/ts**: SDK TypeScript
148+
- **sdk/py**: SDK Python
149+
- **sdk/go**: SDK Go
150+
- **sdk/rust**: SDK Rust
151+
- **sdk/wasm**: SDK WASM
152+
- **integration/\***: Integraciones con frameworks
153+
- **ci**: Workflows CI/CD
154+
155+
### Ejemplos
156+
157+
```
158+
feat(sdk/ts): add post-quantum signature support
159+
fix(core): correct Merkle root computation for single-entry chains
160+
docs(sdk/py): add installation instructions for extras
161+
test(core): add conformance tests for expired bundles
162+
chore(ci): add code coverage to TypeScript SDK workflow
163+
```
164+
165+
## Requisitos de Testing
166+
167+
- Todas las nuevas funcionalidades deben incluir tests correspondientes.
168+
- Las correcciones de bugs deben incluir un test de regresión que hubiese atrapado el bug.
169+
- Los tests de conformidad en `tests/conformance/` verifican el cumplimiento del protocolo en todas las implementaciones.
170+
- Los tests de los SDKs deben cubrir la creación de bundles, firma, verificación y casos de error.
171+
- CI debe pasar antes de que un PR pueda ser mergeado. Los fallos de tests no se suprimen — si los tests fallan, el build falla.
172+
173+
## ¿Preguntas?
174+
175+
Si tienes preguntas sobre cómo contribuir, abre un issue en GitHub o inicia una discusión. Estaremos encantados de ayudarte a empezar.

0 commit comments

Comments
 (0)