# 번역

Blockstudio는 번역 파일을 `languages` 폴더에 포함합니다. 사이트 언어나 사용자 프로필의 언어가 지원 언어와 일치하면 WordPress가 해당 번역을 사용합니다. Blockstudio를 플러그인, 필수 플러그인 또는 Composer 패키지로 실행할 때도 동일하게 작동합니다.

## 사용 가능한 언어

Blockstudio에는 번들로 포함된 `languages/locales.json`에 기록된 WordPress개의 로캘 번역이 포함되어 있으며, 지역별 변형과 존댓말·반말 변형도 지원합니다. 영어(`en_US`)는 원본 언어이므로 번역 파일이 필요하지 않습니다. 이 목록은 GlotPress에서 WordPress가 지원하는 로캘과 WordPress 코어 번역 API에서 제공하는 변형을 합친 것입니다.

기존 독일어(`de_DE`) 및 격식체 독일어(`de_DE_formal`) 번역은 그대로 유지됩니다. 추가 번역은 GPT-6 Luna로 생성되며, `.po` 헤더에 기계 생성 번역으로 표시됩니다. 자동 완전성 및 형식 검사를 통과했지만, 모든 번역을 원어민이 검토한 것은 아닙니다. 수정 제안을 환영합니다.

번역에는 블록 편집기의 필드 컨트롤, 관리 페이지, 캔버스, 개발자 도구 오버레이 및 REST 엔드포인트의 메시지가 포함됩니다. 자체 `block.json` 파일의 레이블과 도움말은 테마 또는 플러그인에 속하며 해당 텍스트 도메인을 사용합니다.

**설정 > 일반 > 사이트 언어**에서 언어를 선택하거나 WordPress 프로필에서 개인 언어를 지정하세요. Blockstudio가 해당 로캘을 자동으로 사용합니다. WordPress 언어 선택기에 언어를 추가하지는 않습니다. 로캘은 WordPress 설치에서도 사용할 수 있어야 합니다. 사이트에서 AI 요청이나 번역 구독, 추가 런타임 설정이 필요하지 않습니다.

## 번역 재정의

`wp-content/languages/plugins`의 번역 파일은 번들 파일보다 우선 적용됩니다. PHP 문자열(`blockstudio-de_DE.mo` 또는 `blockstudio-de_DE.l10n.php`)뿐 아니라 스크립트(스크립트 핸들마다 파일 하나, 예: `blockstudio-de_DE-blockstudio-blocks.json`)에도 적용됩니다.

## 번역에 참여하기

각 언어는 `.po` 파일로 제공되며, 텍스트 편집기나 Poedit 같은 번역 도구로 편집할 수 있습니다. 수정 및 새 언어 추가를 위한 풀 리퀘스트를 환영합니다.

1. 언어를 추가하려면 `languages/blockstudio.pot`를 `languages/blockstudio-<locale>.po`로 복사합니다(예: `blockstudio-fr_FR.po`). 그런 다음 `Language` 및 `Plural-Forms` 헤더를 설정합니다. 기존 언어를 개선하려면 해당 `.po` 파일을 편집합니다.
2. 문자열을 번역합니다. 번역문에 `%1$s` 같은 플레이스홀더를 그대로 유지합니다.
3. `npm run i18n`을 실행합니다. `.mo`, `.l10n.php` 및 `.json` 파일이 생성되며, WordPress가 이를 불러옵니다.
4. 생성된 파일과 함께 `.po` 파일을 커밋하고 풀 리퀘스트를 엽니다.

`npm`을 실행할 수 없다면 `.po` 파일만 포함한 풀 리퀘스트도 괜찮습니다. 병합 전에 생성된 파일을 추가할 수 있습니다.

## 누락된 번역 생성

유지 관리자는 인증된 Codex CLI을 사용해 누락된 항목을 생성할 수 있습니다. 이는 선택 사항인 개발 명령이며, WordPress가 실행하는 기능은 아닙니다.

```bash
npm run i18n:translate -- --dry-run
npm run i18n:translate
```

기본 모델은 `gpt-6-luna`입니다. 하나의 로캘만 작업하려면 `npm run i18n:translate -- --locale fr_FR`을 사용합니다. 이 명령은 최신 원본 문자열을 추출하고, 누락된 번역을 채운 다음 `.mo`, `.l10n.php` 및 스크립트별 `.json` 파일을 컴파일합니다. 공개 인터페이스 문자열과 그 문맥 및 기존 번역 형식만 Codex에 전송됩니다. 사이트 콘텐츠나 사용자 데이터는 전송되지 않습니다.

기존의 비어 있지 않은 번역은 덮어쓰지 않습니다. 완료된 배치는 저장되므로 중단 후 명령을 다시 실행하면 누락된 작업부터 이어서 진행합니다. `%1$s` 같은 플레이스홀더, HTML 마크업, 기술 식별자 및 필수 복수형은 저장 전에 검증됩니다. 퍼지 항목과 원본의 복수형이 바뀐 항목은 번역자가 검토하도록 남겨 둡니다. 요청한 모델을 사용할 수 없어도 다른 모델로 대체하지 않습니다.

`npm run i18n:locales`은 WordPress/GlotPress에서 로캘 목록과 복수형 규칙을 새로고침합니다. `npm run i18n:coverage`는 체크인된 목록에 있는 모든 로캘이 완전한지 확인합니다. 커버리지 검사와 일반 CI는 AI를 호출하거나 로캘 데이터를 가져오지 않습니다. 배치 처리, 동시성 및 복구 옵션은 저장소의 README를 참조하세요.

## 코드에서 번역 가능한 문자열

- PHP: `blockstudio` 텍스트 도메인과 함께 WordPress 함수를 사용합니다. 예: `__( 'Invalid block.', 'blockstudio' )`.
- JavaScript: `@/utils/__`에서 `__`를 가져와 리터럴 문자열을 전달합니다. 예: `__( 'Add row' )`. 런타임에 조립되는 문자열은 번역할 수 없으므로 각 변형에 리터럴 문자열 하나를 사용합니다.
- 번역 가능한 문자열이 포함된 새 스크립트 번들에는 `scripts/i18n.ts` 항목과 동일한 핸들 및 `Translations::script_path()`을 사용하는 `wp_set_script_translations()` 호출이 필요합니다.

문자열을 변경한 후 `npm run i18n`을 실행합니다. 그러면 `languages/blockstudio.pot`과 모든 `.po` 파일이 업데이트됩니다. 번역가나 `npm run i18n:translate`이 채우기 전까지 새 문자열은 영어로 유지됩니다. CI는 `npm run i18n:check`와 `npm run i18n:coverage`를 실행하여 오래된 컴파일 파일, 추출 문제 또는 불완전한 로캘 적용 범위를 거부합니다. 생성은 계속해서 유지 관리자가 명시적으로 수행하는 작업입니다.