개발자를 위한 마크다운 문서 번역 방법

오픈소스 프로젝트는 문서화에 따라 생존하거나 죽는다. 영어로만 된 훌륭한 README를 가진 라이브러리는 중국, 일본, 브라질의 개발자들에게 절대 도달하지 못한다—이 시장들은 전 세계 개발자 인구의 40%를 차지한다. 그러나 마크다운 문서 번역은 독특하게 도전적이다: 코드 블록을 보존하고, 링크 구조를 유지하며, 버전 관리를 처리하고, 프로젝트가 진화함에 따라 번역을 동기화해야 한다.

GitHub의 2024 Octoverse 보고서에 따르면, 오픈소스 기여의 78%가 영어 비원어민에게서 나오지만, 문서의 92%는 여전히 영어로만 되어 있다. 이는 채택, 기여, 글로벌 커뮤니티 구축에 막대한 장벽을 만든다.

이 포괄적인 가이드는 마크다운 문서를 효과적으로 번역하는 방법을 보여줄 것이다: 코드 구문과 링크를 보존하는 것부터 Git에서의 번역 워크플로우 관리, 업데이트 자동화, Docusaurus, VuePress, MkDocs 같은 도구로 다국어 문서 사이트 구축까지.

마크다운 문서 번역이 다른 이유

마크다운은 기술 문서를 위해 설계된 마크업 언어다. 마크다운 문서를 번역할 때, 단순히 산문을 번역하는 것이 아니다—코드, 형식 구문, 하이퍼링크, 버전 관리, 지속적인 업데이트의 복잡한 조합을 관리해야 한다.

마크다운 번역의 도전 과제

1. 코드 블록은 절대 번역하지 말아야 한다

## Installation

Run the following command:

```bash
npm install awesome-library

When translating to Spanish:

• "Installation" → "Instalación" ✅
• "Run the following command:" → "Ejecuta el siguiente comando:" ✅
• npm install awesome-library → KEEP UNCHANGED ✅

Generic translators often break by translating code!

**2. 마크다운 구문을 보존해야 한다**

```markdown
**Bold text** should stay **bold**
*Italic text* should stay *italic*
[Link text](url) should maintain link structure
`inline code` should keep backticks

Bad translation might produce:
**Negrita** (loses markdown syntax)
*Cursiva (missing closing asterisk)
[Texto](url (broken link)

3. 상대 링크는 언어 버전에 맞게 업데이트해야 한다

English: [See API Reference](./api-reference.md)
Spanish: [Ver Referencia API](./referencia-api.md)
         ^link text translated  ^filename also translated

Both must exist and link correctly!

4. 문서는 진화한다—번역도 그래야 한다

Day 1: Translate README.md (English → Spanish)
Day 15: English README.md updated (new feature added)
Problem: Spanish version is now outdated!

Need workflow to track and sync translation updates.

실제 영향

성공 사례: Vue.js

• 문서를 10개 이상 언어로 번역
• 중국어 번역이 아시아 채택에 핵심적
• GitHub를 통한 커뮤니티 주도 번역 워크플로우
• 결과: npm 다운로드의 40%가 아시아에서, 거대한 중국 커뮤니티

성공 사례: React

• 커뮤니티가 관리하는 30개 이상 언어의 공식 번역
• 각 언어별 별도 레포 (react.dev, zh-hans.react.dev, es.react.dev)
• 번역 가이드와 자동화 도구 제공
• 결과: 글로벌 개발자 채택, 100개 이상 국가에서의 기여

성공 사례: Rust 프로그래밍 언어

• "The Rust Book"을 15개 이상 언어로 번역
• 커뮤니티가 mdBook을 통해 번역 유지
• 일본어 번역으로 일본 Rust 개발자 300% 증가
• 활성 번역 팀이 영어 업데이트와 동기화 유지

실패 사례: 버려진 번역 많은 오픈소스 프로젝트가 오래된 번역을 가지고 있다:

• 프랑스어 README는 2년 전에 마지막 업데이트
• 영어 README는 매주 업데이트
• 결과: 프랑스어 개발자 혼란, 프로젝트 포기 또는 오래된 정보로 고군분투

번역을 위한 마크다운 기본 요소

핵심 마크다운 요소

헤더:

# Heading 1
## Heading 2
### Heading 3

Translate text, preserve symbols:
# Installation → # Instalación
## Quick Start → ## Inicio Rápido

강조:

**bold text** → **texto en negrita**
*italic text* → *texto en cursiva*
~~strikethrough~~ → ~~tachado~~

Keep markdown syntax exactly as-is.

목록:

Unordered:
- Item one
- Item two
  - Nested item

Ordered:
1. First step
2. Second step
3. Third step

Translate content, keep structure:
- Primer elemento
- Segundo elemento
  - Elemento anidado

링크:

[Link text](url)
[Documentation](https://example.com/docs)

Translate text, keep URL (unless also translating linked page):
[Documentación](https://example.com/docs)

Or if Spanish docs exist:
[Documentación](https://example.com/es/docs)

이미지:

![Alt text](image-url "Optional title")

![Dashboard screenshot](./images/dashboard.png "Admin Dashboard")

Translate alt text and title:
![Captura de pantalla del panel](./images/dashboard.png "Panel de Administración")

Image filename usually stays the same (shared resource).

코드 블록:

Inline code: Use `npm install` to install packages.

프로세 번역, 코드 보존: npm install을 사용하여 패키지를 설치하세요.

Fenced code blocks:

function greet(name) {
  console.log(`Hello, ${name}!`);
}

코드 블록 내부의 코드는 절대 번역하지 마세요. 그대로 유지하세요.

**테이블:**
```markdown
| English | Spanish | French |
|---------|---------|--------|
| Hello   | Hola    | Bonjour|
| Goodbye | Adiós   | Au revoir|

내용 셀 번역, 구조 유지:
| 영어  | 스페인어 | 프랑스어 |
|---------|---------|---------|
| Hello   | Hola    | Bonjour |
| Goodbye | Adiós   | Au revoir|

고급 마크다운 기능

인용 블록:

> This is important information that users should know.

내용 번역, > 기호 유지:
> 사용자가 알아야 할 중요한 정보입니다.

수평선:

---
or
***
or
___

변경하지 말기 (시각적 구분선, 텍스트 없음).

마크다운 내 HTML:

<div class="warning">
  Be careful when using this feature!
</div>

HTML 태그 유지, 내용 번역:
<div class="warning">
  이 기능을 사용할 때 주의하세요!
</div>

각주:

Here is a footnote reference[^1].

[^1]: This is the footnote content.

참조 맥락과 각주 텍스트 모두 번역:
여기에 각주 참조가 있습니다[^1].

[^1]: 이것은 각주 내용입니다.

마크다운 문서 번역 워크플로

옵션 1: 언어별 별도 파일 (권장)

디렉토리 구조:

docs/
├── en/
│   ├── README.md
│   ├── installation.md
│   ├── api-reference.md
│   └── troubleshooting.md
├── es/
│   ├── README.md
│   ├── instalacion.md
│   ├── referencia-api.md
│   └── solucion-problemas.md
├── fr/
│   ├── README.md
│   ├── installation.md
│   ├── reference-api.md
│   └── depannage.md
└── zh/
    ├── README.md
    ├── installation.md
    ├── api-reference.md
    └── troubleshooting.md

장점: ✅ 깔끔한 분리 (혼합 언어 없음) ✅ 필요에 따라 언어별 파일 구조 다르게 가능 ✅ 어떤 파일이 번역되었는지 쉽게 확인 ✅ 동일 언어 내 링킹 간단

단점: ❌ 어떤 번역이 오래되었는지 추적 어려움 ❌ 관리할 파일 많음

옵션 2: 접미사 기반 (대안)

디렉토리 구조:

docs/
├── README.md (English default)
├── README.es.md (Spanish)
├── README.fr.md (French)
├── README.zh.md (Chinese)
├── installation.md
├── installation.es.md
├── installation.fr.md
└── installation.zh.md

장점: ✅ 번역 파일이 원본 옆에 있음 (누락된 번역 쉽게 발견) ✅ 기본 이름으로 알파벳 순 정렬

단점: ❌ 언어 많아지면 복잡해짐 ❌ 언어별 문서 탐색 어려움

결론: 포괄적인 문서화 프로젝트에는 별도 디렉토리 사용.

단계별 번역 프로세스

단계 1: 번역 디렉토리 구조 설정

# 언어 디렉토리 생성
mkdir -p docs/es docs/fr docs/zh

# 영어 구조를 새 언어로 복사
cp -r docs/en/* docs/es/

# 이제 docs/es/의 각 파일 번역

단계 2: 번역 추적 생성

translation-status.md:

# Translation Status

## Spanish (es)

| File | Status | Last Updated | Translator |
|------|--------|--------------|------------|
| README.md | ✅ Current | 2025-01-25 | @translator1 |
| installation.md | ⚠️ Outdated | 2025-01-10 | @translator1 |
| api-reference.md | ❌ Not started | - | - |

## French (fr)

| File | Status | Last Updated | Translator |
|------|--------|--------------|------------|
| README.md | ✅ Current | 2025-01-22 | @translator2 |
| installation.md | ✅ Current | 2025-01-22 | @translator2 |

또는 자동화 도구 사용 (나중에 설명).

단계 3: 코드 블록 보존하며 번역

원본 (en/installation.md):

# Installation

## Prerequisites

- Node.js 18+
- npm or yarn

## Install via npm

Run the following command in your terminal:

```bash
npm install awesome-library

Verify Installation

Create a test file test.js:

const awesome = require('awesome-library');
console.log(awesome.version);

Run it:

node test.js

You should see the version number printed.

**번역본 (es/instalacion.md):**
```markdown
# Instalación

## Prerequisitos

- Node.js 18+
- npm o yarn

## Instalar vía npm

Ejecuta el siguiente comando en tu terminal:

```bash
npm install awesome-library

Verificar la Instalación

Crea un archivo de prueba test.js:

const awesome = require('awesome-library');
console.log(awesome.version);

Ejecútalo:

node test.js

Deberías ver el número de versión impreso.

**변경된 점:**
- 헤더 번역
- 산문 번역
- 코드 블록 변경 없음 (bash 명령어, JavaScript 코드)
- 인라인 코드 변경 없음 (`test.js`, npm 패키지 이름)
- 파일 구조 유지

**단계 4: 내부 링크 업데이트**

**English (en/README.md):**
```markdown
See [Installation Guide](./installation.md) for setup instructions.

API 참조 문서를 확인하세요 (API 참조).

스페인어 (es/README.md):

Consulta la [Guía de Instalación](./instalacion.md) para instrucciones de configuración.

Revisa la [Referencia de API](./referencia-api.md) para documentación detallada.

중요:

• 링크 텍스트 번역
• 링크 URL을 스페인어 파일명으로 업데이트
• 스페인어 파일이 실제로 존재해야 함!

5단계: Git에 커밋하기

git add docs/es/
git commit -m "Add Spanish translation of installation docs"
git push origin main

특별한 경우 처리

1. 코드 블록 내 코드 주석

주석을 번역해야 할까요?

## 예시

```javascript
// Initialize the application
const app = createApp();

// Start the server on port 3000
app.listen(3000);

**옵션 A: 코드 주석을 영어로 유지**
```javascript
// Initialize the application
const app = createApp();

// Start the server on port 3000
app.listen(3000);

장점: 범용적 (개발자들은 영어 주석을 읽음) 단점: 초보자에게 덜 접근 가능

옵션 B: 코드 주석 번역

// Inicializar la aplicación
const app = createApp();

// Iniciar el servidor en el puerto 3000
app.listen(3000);

장점: 영어가 아닌 개발자에게 더 접근 가능 단점: 코드 언어가 섞여 복사-붙여넣기 불가능

권장: 프로덕션 코드 예시는 영어로 유지. 튜토리얼/학습 콘텐츠에서는 이해 > 복사-붙여넣기를 우선.

2. 변수 및 함수 이름

코드 내에서는 절대 번역하지 마세요:

// 틀림 - 변수 이름 번역하지 마세요
function obtenerUsuario(idUsuario) {
  return database.buscar(idUsuario);
}

// 맞음 - 코드는 영어로 유지
function getUser(userId) {
  return database.find(userId);
}

예외: 의사코드 또는 개념적 예시

영어:

if user is logged in: show dashboard else: redirect to login

스페인어 (의사코드에 허용됨):

si usuario está conectado: mostrar panel sino: redirigir a inicio de sesión

3. 명령줄 예시

명령은 번역하지 말고 설명만 번역하세요:

영어:
## 새 컴포넌트 생성

CLI를 사용해 컴포넌트를 생성하세요:

```bash
npx create-component MyComponent

이 명령은 src/components/MyComponent/에 새 컴포넌트를 생성합니다.

스페인어:

새 컴포넌트 생성

CLI를 사용해 컴포넌트를 생성하세요:

npx create-component MyComponent

이 명령은 src/components/MyComponent/에 새 컴포넌트를 생성합니다.

**명령은 영어로 유지, 설명은 번역.**

### 4. API 엔드포인트 URL

**URL은 변경하지 마세요:**

```markdown
영어:
### 사용자 프로필 가져오기

GET /api/v1/users/:id

스페인어:
### 사용자 프로필 가져오기

GET /api/v1/users/:id

틀림: `GET /api/v1/usuarios/:id` (API가 깨짐!)

5. 환경 변수 및 설정

변수 이름은 유지, 설명만 번역하세요:

영어:
API 키 설정:

```bash
export API_KEY=your_key_here

스페인어: API 키 설정:

export API_KEY=tu_clave_aqui

API_KEY는 영어로 유지 (환경 변수 이름). your_key_here → tu_clave_aqui (예시 값, 번역 가능).

### 6. 배지 링크 및 쉴드

**README.md 파일에서 흔함:**

```markdown
영어:
[![Build Status](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)
[![npm version](https://badge.fury.io/js/awesome-lib.svg)](https://www.npmjs.com/package/awesome-lib)

스페인어: 배지 그대로 유지
(외부 서비스에서 자동 생성, 언어 무관)

또는 번역된 텍스트 배지 사용 시:
[![Estado de Construcción](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)

보통: 영어 배지 유지 (개발자들이 기대함, 상태는 범용적).

자동화 및 도구

마크다운용 번역 관리 시스템

1. Crowdin

기능:

• GitHub/GitLab 통합
• 마크다운 파일 지원
• 코드 블록 자동 보존
• 커뮤니티 번역 (웹 UI를 통해 기여자 번역)
• 번역 메모리

워크플로:

1. Crowdin을 GitHub 저장소에 연결
2. Crowdin이 docs/en/의 신규/변경 파일 감지
3. 번역자가 Crowdin 웹 인터페이스로 번역
4. Crowdin이 번역 포함 풀 리퀘스트 제출
5. 검토 및 병합

가격: 오픈소스 무료, 상용 $40/월+

2. Lokalise

기능:

• Crowdin과 유사
• 자동화를 위한 더 나은 API
• 마크다운 지원
• 동기화 CLI 도구

워크플로:

# 소스 파일 업로드
lokalise2 file upload --lang-iso en --file docs/en/README.md

# 번역 다운로드
lokalise2 file download --lang-iso es --dest docs/es/

가격: $120/월+

3. Transifex

기능:

• 오픈소스 친화적
• 마크다운 지원
• 번역 검토
• 품질 검사

가격: 오픈소스 무료, 상용 $30/월+

Git 기반 번역 워크플로

방법: 번역을 위한 별도 브랜치 사용

# 메인 브랜치: 영어 문서
git checkout main

# 번역 브랜치 생성
git checkout -b translate/spanish

# 파일 번역
# ...

# 커밋
git add docs/es/
git commit -m "Add Spanish translation"

# 푸시 및 PR 생성
git push origin translate/spanish
# GitHub에서 풀 리퀘스트 열기

장점:

• 번역자가 독립적으로 작업
• PR을 통한 검토 프로세스
• 번역을 기능처럼 추적

방법: Git 메타데이터를 사용한 번역 추적

en/installation.md:

<!--
Last updated: 2025-01-25
번역 상태:
- es: 2025-01-20 (오래됨)
- fr: 2025-01-24 (최신)
- zh: 시작 안 함
-->

# Installation
...

이 주석을 확인하고 오래된 번역을 표시하는 자동화 스크립트.

자동화된 번역 업데이트 감지

오래된 번역 감지 스크립트:

import os
from datetime import datetime

def check_translation_status(base_dir="docs"):
    languages = ['en', 'es', 'fr', 'zh']
    base_lang = 'en'

    for lang in languages:
        if lang == base_lang:
            continue

        en_dir = os.path.join(base_dir, base_lang)
        lang_dir = os.path.join(base_dir, lang)

        for file in os.listdir(en_dir):
            if not file.endswith('.md'):
                continue

            en_file = os.path.join(en_dir, file)
            lang_file = os.path.join(lang_dir, file)

            if not os.path.exists(lang_file):
                print(f"⚠️ {lang}/{file} - 번역 안 됨")
                continue

            en_modified = os.path.getmtime(en_file)
            lang_modified = os.path.getmtime(lang_file)

            if en_modified > lang_modified:
                print(f"❌ {lang}/{file} - 오래됨 (영어 업데이트 후 번역됨)")
            else:
                print(f"✅ {lang}/{file} - 최신")

check_translation_status()

GitHub Action으로 실행:

# .github/workflows/check-translations.yml
name: 번역 상태 확인

on:
  push:
    paths:
      - 'docs/**'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: 번역 확인
        run: python scripts/check-translations.py
      - name: PR에 댓글 달기
        if: github.event_name == 'pull_request'
        run: |
          python scripts/check-translations.py > translation-status.txt
          gh pr comment ${{ github.event.number }} --body-file translation-status.txt

AI 지원 마크다운 번역

마크다운 문서용 AI Trans:

기능:

• 코드 블록 자동 보존
• 마크다운 구문 유지
• 링크 그대로 유지
• 빠름 (몇 분 만에 전체 문서 번역)

워크플로:

# README.md를 영어에서 스페인어로 번역
ai-translator translate \
  --input docs/en/README.md \
  --output docs/es/README.md \
  --source en \
  --target es \
  --format markdown

# 모든 파일 일괄 번역
for file in docs/en/*.md; do
  filename=$(basename "$file")
  ai-translator translate \
    --input "$file" \
    --output "docs/es/$filename" \
    --source en \
    --target es \
    --format markdown
done

가격: 1M 문자당 $10 (Standard) 또는 10M 문자당 $50 (Business) 무료 Starter Pack: 테스트용 100,000 문자 일반 비용 예시:

• 작은 문서 (50K 문자): $0.50
• 중간 문서 (200K 문자): $2
• 큰 문서 (1M 문자): $10

모범 사례: AI 번역 → 인간 검토 → 커밋

다국어 문서 사이트 구축

Docusaurus (React 기반)

설치:

npx create-docusaurus@latest my-docs classic
cd my-docs

i18n 설정 (docusaurus.config.js):

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr', 'zh'],
    localeConfigs: {
      en: { label: 'English' },
      es: { label: 'Español' },
      fr: { label: 'Français' },
      zh: { label: '中文' }
    }
  },
  // ...
};

디렉토리 구조:

docs/
├── intro.md (영어 기본)
├── installation.md
i18n/
├── es/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (스페인어)
│           └── installation.md
├── fr/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (프랑스어)
│           └── installation.md

빌드:

# 모든 언어 빌드
npm run build

# 특정 언어 빌드
npm run build -- --locale es

결과: 자동 언어 전환기, SEO 최적화된 다국어 사이트.

VuePress (Vue 기반)

i18n 설정 (.vuepress/config.js):

module.exports = {
  locales: {
    '/': {
      lang: 'en-US',
      title: 'My Documentation',
      description: 'Documentation for awesome library'
    },
    '/es/': {
      lang: 'es-ES',
      title: 'Mi Documentación',
      description: 'Documentación para awesome library'
    },
    '/fr/': {
      lang: 'fr-FR',
      title: 'Ma Documentation',


      description: '멋진 라이브러리에 대한 문서화'
    }
  },
  themeConfig: {
    locales: {
      '/': {
        selectText: '언어',
        label: 'English',
        nav: [
          { text: '가이드', link: '/guide/' },
          { text: 'API', link: '/api/' }
        ]
      },
      '/es/': {
        selectText: 'Idiomas',
        label: 'Español',
        nav: [
          { text: 'Guía', link: '/es/guide/' },
          { text: 'API', link: '/es/api/' }
        ]
      }
    }
  }
};

**디렉토리 구조:**

docs/ ├── README.md (영어) ├── guide/ │ └── installation.md ├── es/ │ ├── README.md (스페인어) │ └── guide/ │ └── installation.md └── fr/ ├── README.md (프랑스어) └── guide/ └── installation.md

### MkDocs (Python 기반)

**i18n 플러그인으로 설치:**

```bash
pip install mkdocs mkdocs-static-i18n

mkdocs.yml:

plugins:
  - i18n:
      default_language: en
      languages:
        en: English
        es: Español
        fr: Français
      material_alternate: true

nav:
  - Home: index.md
  - Installation: installation.md
  - API Reference: api.md

디렉토리 구조:

docs/
├── index.md (영어 기본)
├── index.es.md (스페인어)
├── index.fr.md (프랑스어)
├── installation.md
├── installation.es.md
├── installation.fr.md

빌드:

mkdocs build

결과: 언어 전환기가 포함된 site/ 생성.

GitHub Pages 배포

다국어 Docusaurus 사이트 배포:

# .github/workflows/deploy.yml
name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install dependencies
        run: npm install
      - name: Build website
        run: npm run build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

접근 방법:

• 영어: https://youruser.github.io/yourrepo/
• 스페인어: https://youruser.github.io/yourrepo/es/
• 프랑스어: https://youruser.github.io/yourrepo/fr/

모범 사례 및 함정

모범 사례

1. 영향력이 높은 페이지부터 시작

우선순위:
1. README.md (사용자가 가장 먼저 보는 것)
2. 설치/시작하기 (채택의 장애물)
3. API 참조 (개발자들이 필요로 함)
4. 기여 가이드 (국제 기여자를 위한)

초기에는 건너뛰기:
- 변경 로그 (덜 중요)
- 더 이상 사용되지 않는 문서
- 내부 개발자 노트

2. 번역 스타일 가이드 유지

# 번역 스타일 가이드 - 스페인어

## 용어
- "library" → "biblioteca" (서점이 아닌 "librería" 사용 금지)
- "framework" → "framework"로 유지 (널리 이해됨)
- "deploy" → "desplegar" ("implementar" 아님)

## 톤
- 기술 문서에는 격식 있는 "usted" 사용
- 튜토리얼/가이드에는 비격식적인 "tú" 사용
- 간결하게 (스페인어는 평균적으로 영어보다 20% 길음)

## 코드
- 코드 블록은 절대 번역하지 않음
- 널리 사용되는 기술 용어는 영어로 유지

3. 번역 버전 관리

README.md:
<!--
Translation: Spanish
Source version: v2.5.0
Translated: 2025-01-25
Translator: @username
-->

# Instalación
...

이렇게 하면 번역이 뒤처진 시점을 추적할 수 있습니다.

4. 커뮤니티 기여 장려

## 번역 기여

번역을 환영합니다! 기여 방법:

1. 이 저장소를 포크
2. `docs/[언어-코드]/` 디렉토리 생성
3. `docs/en/`의 파일 번역
4. 풀 리퀘스트 제출

번역 가이드: [TRANSLATION.md](./TRANSLATION.md)

일반적인 함정

함정 1: URL 및 파일 경로 번역

❌ 잘못됨:
[See installation](./instalación.md)
# 파일이 존재하지 않음 (강세 부호 포함)

✅ 올바름:
[See installation](./instalacion.md)
# 파일: instalacion.md (파일명에 강세 부호 없음)

함정 2: 상대 링크 깨짐

영어: docs/en/guide.md → ../assets/image.png 링크
스페인어: docs/es/guia.md → ../assets/image.png (동일 경로!)

스페인어 번역자가 ./assets/image.png 작성 시 (깨짐!)

함정 3: 이미지 alt 텍스트 잊음

![](./screenshot.png)

이렇게 해야 함:
![Dashboard screenshot](./screenshot.png)

스페인어:
![Captura de pantalla del panel](./screenshot.png)

접근성을 위해 alt 텍스트가 중요합니다!

함정 4: 일관되지 않은 용어 사용

페이지 1: "servidor" (서버)
페이지 3: "server" (영어로 유지)
페이지 5: "servidor" 다시

하나 선택하고 일관되게 사용! 용어집 사용.

성공 측정

추적할 지표

1. 언어별 문서 사용량

Google Analytics (문서 사이트):
- 언어별 트래픽 (es, fr, de 등)
- 페이지 체류 시간 (높을수록 더 잘 이해함)
- 이탈률 (모국어 문서에서 낮음)

예시:
영어 문서: 사용자 70%
스페인어 문서: 사용자 15% (성장 중!)
프랑스어 문서: 사용자 10%
기타: 5%

2. GitHub 인사이트

GitHub Issues:
- 각 언어로 제출된 이슈 수
- 비영어 이슈에 대한 응답 시간

Pull Requests:
- 비영어권 국가의 기여
- 스페인어 문서 이후: LATAM 개발자 기여 +40%

Stars/Forks:
- 번역 릴리스 후 성장 추적

3. 커뮤니티 성장

Discord/Slack:
- 언어별 채널 활동
- 모국어로 된 질문

Stack Overflow:
- 라이브러리에 태그된 다양한 언어의 질문

4. npm/PyPI 지역별 다운로드

npm 국가별 다운로드 통계:
중국어 번역 전:
- 중국: 다운로드의 5%

중국어 번역 후:
- 중국: 다운로드의 22% (4.4배 성장!)

비용 및 ROI

번역 투자

작은 오픈소스 라이브러리 (문서 5,000단어):

전문 번역:

번역: 5,000 × $0.08 = 언어별 $400
검토: $100
언어별 총계: $500

3개 언어 (es, fr, zh): $1,500

AI 보조 번역:

AI 번역 (AI Trans): 5,000단어 × 평균 6자 = 30,000자 = $0.30
기술 검토자: 5시간 × $75 = $375
언어별 총계: $375.30

3개 언어: $1,126 (25% 절감)

커뮤니티 기여 (무료지만 느림):

Crowdin 설정: 오픈소스 무료
번역: 무료 (커뮤니티 자원봉사자)
검토 시간: 본인 시간 (언어별 5-10시간)

3개 언어: 금전 비용 $0, 시간 투자 15-30시간

오픈소스 프로젝트의 ROI

ROI는 항상 금전적이지 않음—커뮤니티 성장입니다:

스페인어/중국어 번역 전 지표:
- 월 npm 다운로드: 50,000
- GitHub 스타: 2,500
- 기여자: 40명 (주로 미국/유럽)

번역 6개월 후:
- 월 npm 다운로드: 120,000 (140% 성장)
- GitHub 스타: 6,800 (172% 성장)
- 기여자: 95명 (LATAM/아시아에서 55명 신규)

커뮤니티 가치: 무한대
비용: AI 보조 + 검토 $1,500

도구 및 리소스

번역 도구

AI Trans

• 마크다운 형식 자동 보존
• 코드 블록 그대로 유지 (코드 번역 안 함)
• 링크 구조 유지
• 1M자당 $10 (Standard) 또는 10M자당 $50 (Business)
• 무료 100K자 starter 팩
• 57개 언어 지원

DeepL API

• 고품질 유럽 언어
• 전처리와 함께 마크다운 지원
• 백만자당 $25 + 월 $5.49 구독

Google Cloud Translation

• 133개 언어
• 광범위한 언어 커버리지에 좋음
• 백만자당 $20
• 마크다운 인식 없음 (전처리 필요)

마크다운 린팅 및 검증

markdownlint

• 마크다운 구문 검증
• 일관된 형식 보장
• CLI 및 에디터 플러그인

npm install -g markdownlint-cli
markdownlint docs/es/*.md

markdown-link-check

• 마크다운 파일의 모든 링크 검증
• 깨진 상대 링크 포착

npm install -g markdown-link-check
markdown-link-check docs/es/README.md

문서 사이트 빌더

Docusaurus (React)

• 최적: React 개발자, 현대 SPA 문서
• i18n 내장
• 무료

VuePress (Vue.js)

• 최적: Vue 개발자
• 간단한 설정
• 무료

MkDocs (Python)

• 최적: Python 프로젝트
• 최소 구성
• 무료

GitBook

• 최적: 비개발자 (GUI 에디터)
• 호스팅 솔루션
• 오픈소스 무료

결론

마크다운 문서를 번역하는 것은 글로벌 개발자 커뮤니티 구축에 가장 큰 영향을 미치는 기여 중 하나입니다. 프로젝트를 여러 언어로 접근 가능하게 함으로써, 수십억 명의 비영어권 개발자의 채택을 해제하고 다양하고 국제적인 협력을 촉진합니다.

주요 요점:

• 코드 블록, 마크다운 구문, 링크 구조 보존
• 깔끔한 조직을 위해 언어별 별도 디렉토리 사용
• Git 워크플로우로 번역 동기화 자동화
• 비용 효과적인 품질을 위해 AI 번역 + 인간 검토 활용
• Docusaurus, VuePress, MkDocs로 다국어 사이트 구축
• 메타데이터와 자동 검사로 번역 추적
• 지속 가능한 번역을 위해 커뮤니티 기여 장려

AI Trans와 같은 현대 AI 도구는 코드 블록, 링크, 형식과 같은 모든 중요한 마크다운 요소를 보존하면서 번역 비용을 70-90% 줄일 수 있습니다. 최적 워크플로우: AI가 초기 문서를 번역 (주가 아닌 분), 기술 검토자가 정확성과 일관성 보장, 커뮤니티가 업데이트 유지 지원.

일반적인 문서 번역 비용:

• 소형 프로젝트 (50K자): AI Trans $0.50 vs. 인간 번역 $400
• 중형 프로젝트 (200K자): AI Trans $2 vs. 인간 번역 $1,600
• 대형 프로젝트 (1M자): AI Trans $10 vs. 인간 번역 $8,000

시간 절감: 95%+ (주에서 분으로)

작은 유틸리티 라이브러리를 유지하든 주요 오픈소스 프레임워크를 다루든, 번역된 문서는 언어 장벽을 제거하고 전 세계 개발자를 프로젝트에 환영합니다.

문서 번역 준비 되셨나요? AI Trans의 코드 보존 번역 엔진으로 마크다운 문서를 번역 시작하기 하고 전 세계 개발자들에게 다가가세요.