Lingo.dev - Automated AI localization for web & mobile apps

소개

Lingo.dev 컴파일러는 기존 컴포넌트를 변경하지 않고도 React 기반 앱을 현지화할 수 있게 해주는 AI 기반 도구입니다. 몇 가지 설정을 구성하고 앱을 컨텍스트 프로바이더로 감싸기만 하면 됩니다 — 이제 앱이 현지화되었습니다.

이 가이드는 웹 애플리케이션 구축을 위한 풀스택 React 프레임워크인 Next.js에서 Lingo.dev 컴파일러를 설정하는 방법을 설명합니다.

학습 내용

Next.js 프로젝트에서 Lingo.dev 컴파일러를 초기화하는 방법
Next.js와의 호환성을 위해 컴파일러를 구성하는 방법
로케일 간 전환을 위한 로케일 스위처를 설정하는 방법

1단계. API 키 설정

Lingo.dev 컴파일러는 대규모 언어 모델(LLM)을 사용하여 AI로 앱을 현지화합니다. 이러한 모델 중 하나를 사용하려면 지원되는 제공업체의 API 키가 필요합니다.

가능한 빨리 시작하려면 Lingo.dev 엔진을 사용하는 것이 좋습니다 — 매월 10,000 토큰의 무료 사용량을 제공하는 자체 호스팅 플랫폼입니다.

API 키를 설정하려면:

Lingo.dev 엔진에 로그인하세요.
프로젝트 페이지로 이동하세요.
API 키 > 복사를 클릭하세요.

API 키를 환경 변수에 저장하세요:

export LINGODOTDEV_API_KEY="<your_api_key>"

대안: 커스텀 LLM 제공업체

Lingo.dev 엔진을 사용할 필요는 없습니다. 다음을 포함한 여러 커스텀 LLM 제공업체와 통합되도록 컴파일러를 구성할 수 있습니다:

Groq
Google
Mistral
Ollama
OpenRouter

2단계. 패키지 설치

Lingo.dev 컴파일러는 lingo.dev npm 패키지의 일부로 배포됩니다. 설치하려면 선호하는 패키지 관리자를 사용하세요:

npm install lingo.dev

3단계. 컴파일러 초기화

Lingo.dev 컴파일러는 Next.js와 통합되어 빌드 시점에 실행됩니다. 빌드 프로세스에 연결하려면 next.config.ts 파일에 다음과 같은 변경사항을 적용하세요:

컴파일러 가져오기:

import lingoCompiler from "lingo.dev/compiler";

next 메서드로 컴파일러 초기화:
```
const withLingo = lingoCompiler.next({
  sourceRoot: "app",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: true,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});
```
Next.js App Router의 경우 다음 사항을 확인하세요:
- sourceRoot가 "app"으로 설정됨
- rsc가 true로 설정됨
사용 가능한 옵션에 대해 자세히 알아보려면 컴파일러 옵션을 참조하세요.
컴파일러 구성을 기존 구성과 병합하고 내보내기:
```
export default withLingo(config);
```

이 구성을 통해 Lingo.dev 컴파일러는 다음과 같은 작업을 수행합니다:

코드베이스의 추상 구문 트리(AST)를 순회
지역화 가능한 콘텐츠(즉, JSX 요소 내 텍스트 및 특정 속성 값) 찾기
구성된 AI 모델을 사용하여 번역 생성
원본 및 번역된 콘텐츠를 dictionary.js 파일에 저장
지역화된 콘텐츠를 플레이스홀더로 대체

4단계. 지역화된 콘텐츠 로드

컴파일러가 앱을 처리하고 번역을 생성한 후에는 이 지역화된 콘텐츠를 사용자에게 로드하고 제공해야 합니다. 이 과정에는 다음이 포함됩니다:

사용자의 로케일 환경설정에 따라 적절한 사전 로드
컨텍스트 제공자를 통해 로드된 번역을 앱에 제공

app/layout.tsx 파일에서 앱을 LingoProvider 컴포넌트로 감싸고 loadDictionary 함수를 전달하세요:

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      <html lang="en">
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

loadDictionary 함수는 다음과 같은 작업을 수행합니다:

lingo-locale 쿠키에서 현재 로케일을 검색(기본값은 "en")합니다
dictionary.js 파일에서 지역화된 콘텐츠를 로드합니다

LingoProvider 컴포넌트는 컴파일러가 생성한 플레이스홀더를 지역화된 콘텐츠로 대체하는 React 컨텍스트 제공자입니다.

5단계. 로케일 전환기 설정하기

사용자가 로케일 간에 전환할 수 있도록 lingo.dev 패키지에서 LocaleSwitcher를 가져옵니다. 이것은 스타일이 적용되지 않은 컴포넌트로 다음과 같은 기능을 제공합니다:

사용 가능한 로케일의 드롭다운 렌더링
사용자가 로케일을 선택할 수 있음
재방문 시 선택한 로케일을 기억함

이 컴포넌트를 사용하려면 앱 어디에나 삽입하고 locales 속성을 구성된 소스 및 대상 로케일을 포함하는 배열로 설정하세요:

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

대안: 커스텀 로케일 전환기

반드시 LocaleSwitcher 컴포넌트를 사용할 필요는 없습니다. 커스텀 로케일 전환 로직과 UI를 구현할 수 있습니다. 유일한 요구 사항은 활성 로케일을 lingo-locale 쿠키에서 읽고 쓰는 것입니다.

6단계. 앱 실행하기

Lingo.dev 컴파일러가 올바르게 설정되었는지 확인하려면:

개발 서버를 시작합니다:
```
npm run dev
```
localhost:3000으로 이동합니다.
LocaleSwitcher 컴포넌트를 사용하여 로케일 간에 전환합니다.

페이지가 다시 로드되고 현지화된 콘텐츠가 표시되어야 합니다.

대안: 수동으로 쿠키 설정하기

만약 LocaleSwitcher 컴포넌트를 사용하지 않는다면, 현지화가 작동하는지 확인하는 대안은 lingo-locale 쿠키를 수동으로 설정하는 것입니다.

구글 크롬을 사용하는 경우, 다음 지침을 따르세요:

보기 > 개발자 > 개발자 도구로 이동합니다.
애플리케이션 탭으로 이동합니다.
왼쪽 사이드바의 스토리지 아래에서 쿠키를 확장하고 사이트 URL을 선택합니다.
쿠키 테이블에서 아무 곳이나 마우스 오른쪽 버튼으로 클릭하고 추가를 선택합니다.
이름 열에 lingo-locale을 입력합니다.
값 열에 원하는 로케일(예: es)을 입력합니다.
Enter 키를 눌러 쿠키를 저장합니다.
페이지를 새로 고쳐 쿠키를 적용합니다.

추가 자료

컴파일러 작동 방식을 이해하려면 작동 원리를 참조하세요.
컴파일러 구성 방법을 알아보려면 컴파일러 옵션을 참조하세요.

Next.js(App Router) 빠른 시작

소개