Lingo.dev CLI는 구성된 로컬라이제이션 엔진을 통해 웹 앱의 리소스 파일(JSON, YAML, XLIFF, PO, PHP)을 번역합니다. 프레임워크에 i18n을 설정하고, CLI가 번역 파일을 가리키도록 지정한 다음 실행하세요.
작동 방식#
모든 웹 프레임워크에는 리소스 파일에서 번역을 불러오는 i18n 라이브러리가 있습니다. React는 JSON, Angular는 XLIFF, Django는 PO를 사용하는 식입니다. CLI는 이 파일들을 직접 번역하므로 코드 변경 없이도 프레임워크가 번역을 바로 반영합니다.
프레임워크에 i18n 설정하기
프레임워크의 공식 i18n 라이브러리를 사용해 로캘 기반 라우팅, 번역 함수, 소스 언어 리소스 파일을 추가하세요. 아래 각 프레임워크 섹션에서 공식 설정 가이드도 확인할 수 있습니다.
CLI 설정하기
먼저 소스 및 대상 로캘과 번역할 파일 패턴이 담긴 lingo init를 만들기 위해 .lingo/config.json를 실행한 다음, 조직과 엔진을 연결하려면 lingo link를 실행하세요. CLI는 파일 확장자를 기준으로 각 파일 형식을 자동 감지하므로 bucket type은 필요하지 않습니다. .lingo/config.json를 커밋하세요.
번역 실행하기
lingo push을 실행하면 CLI가 로컬라이제이션 엔진을 통해 리소스 파일을 번역합니다. 용어집 규칙, 브랜드 보이스, 모델 선택이 자동으로 적용됩니다.
사전 준비#
CLI를 설치하고 인증하세요:
npm install -g @lingo.dev/cli
lingo loginCLI를 사용하려면 Node.js 22+가 필요합니다. CI에서는 대화형 로그인을 건너뛰고 --api-key 또는 LINGO_API_KEY 환경 변수를 통해 키를 전달하세요.
모든 CLI 실행은 적용할 LLM 모델, 용어집, 브랜드 보이스, 규칙을 결정하는 로컬라이제이션 엔진을 거쳐 콘텐츠를 전송합니다. Lingo.dev 대시보드에서 로컬라이제이션 엔진을 생성한 뒤 API key를 발급하세요. lingo link는 엔진의 orgId와 engineId를 .lingo/config.json에 기록합니다.
AI로 더 빠르게 설정
i18n MCP를 사용하면 프레임워크의 전체 i18n 인프라를 자동으로 스캐폴딩할 수 있습니다. Claude Code, Cursor, GitHub Copilot에 연결한 뒤 "Set up i18n"이라고 프롬프트하면, 에이전트가 13단계 체크리스트에 따라 라우팅, 번역 파일, 언어 전환기까지 구성합니다.
JavaScript 프레임워크#
각 pattern의 로캘 세그먼트는 대상 로캘에 맞게 치환됩니다. 예를 들어 public/locales/en/translation.json는 public/locales/de/translation.json로 바뀝니다. 소스 경로에는 반드시 소스 로캘 코드가 포함되어 있어야 합니다.
react-i18next는 JSON 파일에서 번역을 불러오고, 런타임에 키를 번역 문자열에 매핑하는 useTranslation 훅을 제공합니다.
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}서버 사이드 프레임워크#
Laravel은 로캘 디렉터리별로 구성된 PHP 파일에서 번역을 불러오는 내장 로컬라이제이션을 제공합니다.
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "lang/en/messages.php" }]
}번역 실행#
.lingo/config.json가 준비되면, 하나의 명령으로 모든 리소스 파일을 번역할 수 있습니다:
lingo pushCLI는 소스 로캘 파일을 읽고, lockfile(.lingo/lock.json, 구성 파일과 함께 커밋됨)을 기준으로 마지막 실행 이후 변경된 내용을 계산한 뒤, 변경분만 번역해 대상 로캘 파일에 기록합니다. 기존 번역은 그대로 유지되며, CLI는 누락되었거나 업데이트된 문자열만 채웁니다.
처음 실행하거나 새 대상 로캘을 추가한 뒤에는 전체를 처음부터 번역하세요:
lingo push --backfill-missingglob을 전달해 실행 범위를 일부 파일로 좁힐 수 있습니다:
lingo push "messages/**"번역은 수행하지 않고 다른 곳(예: 다른 머신이나 빌드 단계)에서 최신 번역만 가져오려면 lingo pull를 실행하세요. 번역이 최신 상태인지 확인하는 배포 게이트로는 lingo check를 사용하세요.
