AdonisJS 빠른 시작 - Lingo.dev Compiler

소개

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

이 가이드는 서버 측 애플리케이션 구축을 위한 완전한 기능을 갖춘 Node.js 웹 프레임워크인 AdonisJS와 함께 Lingo.dev 컴파일러를 설정하는 방법을 설명합니다.

사전 요구 사항

AdonisJS 프로젝트가 Inertia.js를 사용하고 있어야 합니다.

학습 내용

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

1단계. API 키 설정

Lingo.dev 컴파일러는 AI로 앱을 현지화하기 위해 대규모 언어 모델(LLM)을 사용합니다. 이러한 모델 중 하나를 사용하려면 지원되는 제공업체의 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 컴파일러는 Vite와 통합되어 빌드 시간에 실행됩니다. Vite의 빌드 프로세스에 연결하려면 vite.config.ts 파일에 다음과 같은 변경을 수행하세요:

컴파일러 가져오기:

import lingoCompiler from "lingo.dev/compiler";

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

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

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

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

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

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

클라이언트 측

inertia/app/app.tsx 파일에서:

lingo.dev/react/client에서 LingoProviderWrapper 컴포넌트와 loadDictionary 함수를 가져옵니다:
```
import {
  LingoProviderWrapper,
  loadDictionary,
} from "lingo.dev/react/client";
```
LingoProviderWrapper 컴포넌트는 컴파일러가 생성한 플레이스홀더를 현지화된 콘텐츠로 대체하는 컨텍스트 제공자입니다.

loadDictionary 함수는:
- lingo-locale 쿠키에서 현재 로케일을 검색합니다
- 로케일이 정의되지 않은 경우 "en"으로 대체합니다
- dictionary.js 파일에서 현지화된 콘텐츠를 로드합니다

App 컴포넌트를 LingoProviderWrapper 컴포넌트로 감싸고 loadDictionary 함수를 전달합니다:

<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>

서버 사이드

inertia/app/ssr.tsx 파일에서 하이드레이션 불일치를 방지하기 위해 동일한 단계를 반복합니다:

import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>;

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:3333으로 이동하세요.
LocaleSwitcher 컴포넌트를 사용하여 로케일 간 전환하세요.

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

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

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

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

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

추가 자료

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