일부 파일 형식에서는 Lingo.dev CLI가 번역 요청에 함께 포함하는 인라인 주석을 지원합니다. 이런 주석은 AI 모델에 맥락을 전달해 용어의 의미를 명확히 하거나, 어조를 지정하거나, 콘텐츠가 UI 어디에 표시되는지 설명할 수 있게 해줍니다.
번역자 노트가 중요한 이유#
"Records"라는 단어는 의료 기록, 음반, 또는 데이터베이스 레코드를 뜻할 수 있습니다. 맥락이 없으면 AI 모델은 추측에 의존할 수밖에 없습니다. 번역자 노트는 이런 모호함을 없애줍니다:
jsonc
{
// Medical context: refers to patient medical records
"records": "Records"
}주석은 번역 요청 시 문자열과 함께 전송되어, 모델이 올바른 의미로 해석하도록 유도합니다.
지원 형식#
현재 번역자 노트는 다음 형식에서 지원됩니다:
| 형식 | 버킷 유형 | 주석 문법 |
|---|---|---|
| JSONC | jsonc | 키 위에 // comment 추가 |
| Xcode String Catalogs | xcode-xcstrings | .xcstrings 파일의 주석 필드 |
JSONC 예제#
jsonc
{
// Navigation menu item - appears in the top header bar
"nav.home": "Home",
// Button label - triggers form submission, keep it short
"form.submit": "Submit",
// "Light" refers to the visual theme, not weight or illumination
"settings.theme.light": "Light"
}JSONC를 사용하려면 i18n.json에서 jsonc 버킷 유형을 설정하세요:
json
{
"buckets": {
"jsonc": {
"include": ["locales/[locale].jsonc"]
}
}
}효과적인 노트 작성법#
효과적인 번역자 노트는 문자열만으로는 드러나지 않는 맥락을 설명합니다:
| 좋은 예 | 이유 |
|---|---|
// Button label in checkout flow | UI 내 위치와 짧게 써야 한다는 점을 모델에 알려줍니다 |
// "Set" means a collection, not the verb | 다의어의 의미를 명확히 구분해줍니다 |
// Formal tone - displayed in legal footer | 문체와 톤에 대한 기대치를 설정합니다 |
문자열 자체를 다시 말하는 노트(// This says Welcome)는 큰 도움이 되지 않습니다.
