아래 예제는 모두 .lingo/config.json가 커밋되어 있고 번역도 이미 반영된 실제 저장소입니다. 그래서 결과물과 나란히 설정을 바로 살펴볼 수 있습니다. 대부분은 실행 가능한 애플리케이션이고, 일부는 파일 형식 자체만 보여주기 위한 예제입니다. 하나를 클론하거나 포크한 다음 lingo link를 실행해 여러분의 엔진을 연결하고 푸시하세요.
먼저 방식을 선택하세요#
CLI로 로컬라이즈하는 방법은 두 가지이며, 어떤 예제가 나에게 맞는지도 이 선택에 따라 달라집니다.
이미 있는 파일을 번역합니다. 프레임워크는 Rails YAML, Android XML, Laravel PHP, ARB, Markdown 같은 자체 형식으로 번역을 관리하고, CLI는 그 파일을 제자리에서 번역합니다. 코드에는 아무 변화도 없습니다. 아래 열한 가지 예제 중 아홉 가지가 여기에 해당합니다.
키 없이 작성합니다. 문자열이 있는 곳에서 l.text(...)로 감싸면 lingo extract가 해시 키 기반 카탈로그를 만들어 주므로, 번역 키를 따로 이름 짓거나 관리할 필요가 없습니다. 대신 빌드 단계와 런타임 패키지가 추가로 필요하며, 아래 두 웹 앱 예제가 바로 이 방식을 보여 줍니다.
모바일 앱#
| 예시 | 형식 | 선정 이유 |
|---|---|---|
| iOS | xcode-xcstrings | 하나의 String Catalog에 모든 로캘이 들어 있으므로 대상 경로는 소스 경로와 같습니다. |
| Android | android | 소스는 순수한 values/만 사용하고, Android 고유 한정자(values-pt-rBR/)를 활용합니다 |
| Flutter | flutter | @-metadata와 ICU 플레이스홀더는 유지하고, @@locale는 파일별로 다시 씁니다 |
웹 앱#
키 없이 작업하는 두 가지 예제입니다. 둘 다 문자열을 l.text(...)로 감싸고 lingo extract로 카탈로그를 생성하므로, 가운데 열에는 파일 형식이 아니라 런타임 패키지 이름이 표시됩니다.
| 예시 | 패키지 | 선정 이유 |
|---|---|---|
| React + Vite | @lingo.dev/react | 키 없는 작성 방식으로, 생성된 선언이 l.text()를 추출된 문자열로 좁혀 줍니다 |
| Next.js | @lingo.dev/react-next | 키 없는 작성 방식에 로캘 라우팅, hreflang, 그리고 스위처까지 포함: Pages Router |
프로덕션 환경에서의 hreflang
LingoHead는 기본값이 빈 문자열인 hreflang prop을 바탕으로 baseUrl URL을 만들기 때문에, 별도 설정 없이 쓰면 태그가 상대 URL로 생성됩니다. 검색 엔진은 절대 URL을 기대하므로, 실제로 사용하기 전 사이트의 origin(<LingoHead baseUrl="https://example.com" />)을 전달해 주세요.
콘텐츠와 스펙#
| 예시 | 형식 | 선정 이유 |
|---|---|---|
| Markdown 문서 | md, mdx | 기본은 본문 중심이며, frontmatter 필드와 MDX props는 선택적으로 포함합니다 |
| Markdoc | markdoc, json | 한 번의 푸시로 Next.js 콘텐츠와 UI 문자열까지 — 항목은 3개, 각각 옵션이 다릅니다 |
| OpenAPI | yaml-openapi | 요약과 설명만 대상으로 하며, 경로, operation IDs, enum은 건드리지 않습니다 |
프레임워크 카탈로그#
| 예시 | 형식 | 선정 이유 |
|---|---|---|
| Rails | yaml-root-key | 로캘이 YAML 루트 키이므로, 루트 키 자체를 다시 씁니다 |
| Laravel | php, po | Laravel 카탈로그와 gettext 파일을 함께 사용하며, :name 플레이스홀더는 둘 다 그대로 유지됩니다 |
| TypeScript 모듈 | typescript | JSON 대신 TypeScript 모듈을 카탈로그로 사용합니다. 형식만 보여주는 예제로, 이를 사용하는 앱은 없습니다. |
TypeScript 카탈로그에는 default export가 필요합니다
typescript 형식은 default export인 export default { … }를 읽으며, as const가 있든 없든 상관없습니다. named export만 있으면 번역 가능한 콘텐츠는 생성되지 않고, 실행은 소스를 그대로 복사한 채 끝납니다. 따라서 푸시 결과에 파일은 로컬라이즈된 것으로 나오는데 출력 토큰이 거의 0이라면, 가장 먼저 export 형태부터 확인해 보세요.
이 예제 활용하기#
npm install -g @lingo.dev/cli
lingo login
lingo link # writes your own orgId and engineId into .lingo/config.json
lingo push --wait어느 예제도 orgId이나 engineId는 커밋하지 않습니다. 그래야 포크한 저장소가 다른 사람의 엔진으로 푸시되지 않기 때문입니다. lingo link가 두 값 모두를 로컬에서 채워 넣습니다.
CLI 대신 GitHub App을 쓰고 싶다면
GitHub App은 저장소에 커밋된 engineId에서 .lingo/config.json를 읽어 옵니다. 조직은 App 설치 정보에서 자동으로 확인되지만, 엔진은 반드시 그 파일 안에 있어야 합니다. 포크한 뒤에는 lingo link를 실행하고, App을 설치하기 전에 업데이트된 설정을 커밋하세요.
모든 형식에 예시가 있는 것은 아닙니다#
이 11가지 예시는 사람들이 가장 자주 묻는 프레임워크를 다루지만, CLI는 총 18가지 형식을 번역합니다. xliff, srt, Xcode .strings와 .stringsdict, 범용 yaml, 그리고 독립형 JSON/JSONC까지 모두 여기 저장소가 없어도 사용할 수 있습니다. 전체 목록과 각 형식에 필요한 설정은 Formats에서 확인하세요.
