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

소개

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

이 가이드는 Remix 위에 구축된 Kent C. Dodds의 풀스택 웹 앱 프레임워크인 The Epic Stack과 함께 Lingo.dev 컴파일러를 설정하는 방법을 설명합니다.

배울 내용

The Epic Stack에서 Lingo.dev 컴파일러를 초기화하는 방법
The Epic Stack과 호환되도록 컴파일러를 구성하는 방법
로케일 간 전환을 위한 로케일 스위처 설정 방법

1단계. API 키 설정

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

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

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 컴파일러는 Vite와 통합되어 빌드 시간에 실행됩니다. Vite의 빌드 프로세스에 연결하려면 vite.config.ts 파일에 다음과 같은 변경을 수행하세요:

컴파일러 가져오기:

import lingoCompiler from "lingo.dev/compiler";

vite 메서드로 컴파일러 초기화:
```
const withLingo = lingoCompiler.vite({
  sourceRoot: "app",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});
```
Epic Stack과의 호환성을 위해 다음 사항을 확인하세요:
- sourceRoot가 "app"으로 설정되어 있는지
- rsc가 false로 설정되어 있는지
사용 가능한 옵션에 대해 자세히 알아보려면 컴파일러 옵션을 참조하세요.

컴파일러 구성을 기존 구성과 병합하고 내보내기:

export default defineConfig((config) => {
  const configWithSentry = {
    ...viteConfig,
    plugins: [
      ...viteConfig.plugins!.filter(Boolean),
      MODE === "production" && process.env.SENTRY_AUTH_TOKEN
        ? sentryReactRouter(sentryConfig, config)
        : null,
    ].filter(Boolean),
  };

  return withLingo(configWithSentry);
});

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

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

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

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

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

사전 로딩

app/root.tsx 파일에서:

lingo.dev/react/react-router에서 loadDictionary 함수를 가져옵니다:
```
import { loadDictionary } from "lingo.dev/react/react-router";
```
이 함수는 다음과 같은 작업을 수행합니다:
- lingo-locale 쿠키에서 현재 로케일을 검색합니다
- 로케일이 정의되지 않은 경우 "en"으로 대체합니다
- dictionary.js 파일에서 현지화된 콘텐츠를 로드합니다

loader 함수에서 loadDictionary 함수를 호출합니다:

const lingoDictionary = await loadDictionary(request);

로더 데이터의 일부로 사전을 반환합니다:

return data(
  {
    user,
    requestInfo: {
      hints: getHints(request),
      origin: getDomainUrl(request),
      path: new URL(request.url).pathname,
      userPrefs: {
        theme: getTheme(request),
      },
    },
    ENV: getEnv(),
    toast,
    honeyProps,
    lingoDictionary,
  },
  {
    headers: combineHeaders(
      { "Server-Timing": timings.toString() },
      toastHeaders,
    ),
  },
);

번역 제공하기

app/root.tsx 파일에서:

lingo.dev/react/client에서 LingoProvider 컴포넌트를 가져옵니다:
```
import { LingoProvider } from "lingo.dev/react/client";
```
이 컴포넌트는 컴파일러가 생성한 플레이스홀더를 현지화된 콘텐츠로 대체하는 React 컨텍스트 제공자입니다.
Layout 컴포넌트에서 데이터 로더에서 데이터를 가져옵니다:
```
const data = useLoaderData<typeof loader | null>();
```

앱을 LingoProvider 컴포넌트로 감쌉니다:

<LingoProvider>{/* 기존 앱 코드 */}</LingoProvider>

로드된 사전을 컴포넌트에 전달합니다:

<LingoProvider dictionary={data?.lingoDictionary}>
  {/* 기존 앱 코드 */}
</LingoProvider>

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를 눌러 쿠키를 저장하세요.
쿠키를 적용하려면 페이지를 새로고침하세요.

추가 자료

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

에픽 스택을 위한 빠른 시작

소개