🤨 lingui

이번에 회사에서 https://lingui.dev/introduction 해당 라이브러리를 사용해서 현재 다국어 작업이 필요한 프로젝트에 추가하는 작업을 진행 중인데, 나도 잠시 작업을 함께 진행하게 되면서 알게 된 lingui에 대해 간단하게 정리해 보았다.

1. Lingui 초기 설정

먼저 Lingui CLI와 필요한 패키지를 설치가 필요한데, @lingui/cli는 CLI 도구로 메시지 추출 및 번역 관리를 돕고, @lingui/macro는 코드를 분석하여 번역이 필요한 텍스트를 인식하고, @lingui/react는 React에서 사용할 컴포넌트를 제공한다.

npm install @lingui/cli @lingui/macro @lingui/react

그리고 lingui.config.js를 생성해서 locales 배열에 다국어 지원을 원하는 언어 코드를 추가하고, sourceLocale에는 기본 언어 설정이 필요하다.

module.exports = {
  // 스페인어를 지원한다고 가정
  locales: ["es"],
  sourceLocale: "ko",
  format: "po",  
  catalogs: [{
    path: "locales/{locale}/messages",
    include: ["src"],
  }],
};

2. 자주 사용되는 매크로들

💗 JS 매크로

✨t✨
가장 기본 매크로! ICU 메시지 형식의 문자열을 생성하며, 태그 된 템플릿 리터럴로 변환된다.

import { t } from "@lingui/macro";
const message = t`Hello World`;

//// 변환된 코드 ↓ ↓ ↓ ↓ ↓ ↓

import { i18n } from "@lingui/core";
const message = i18n._(
  /*i18n*/ {
    id: "mY42CM",
    message: "Hello World",
  }
);

변수와 함께 사용 가능하다.

import { t } from "@lingui/macro";
const message = t`My name is ${name}`;

//// 변환된 코드 ↓ ↓ ↓ ↓ ↓ ↓

import { i18n } from "@lingui/core";
const message = i18n._(
  /*i18n*/ {
    id: "mVmaLu",
    message: "My name is {name}",
    values: { name },
  }
);

단순 변수를 제외하고도 여러 표현식들이 템플릿 리터럴에 포함할 수도 있지만, 이런 경우 표현식은 숫자 인덱스로 참조된다.

import { t } from "@lingui/macro";
const message = t`Today is ${new Date()}`;

// 변환된 코드
import { i18n } from "@lingui/core";
const message = i18n._(
  /*i18n*/ {
    id: "2aJT27",
    message: "Today is {0}",
    values: { 0: new Date() },
  }
);

메시지 설명자를 함께 추가할 수 있다.

import { t } from "@lingui/macro";
const message = t({
  id: "msg.hello",
  comment: "Greetings at the homepage",
  message: `Hello ${name}`,
});

// 변환된 코드
import { i18n } from "@lingui/core";
const message = i18n._(
  /*i18n*/ {
    id: "msg.hello",
    comment: "Greetings at the homepage",
    message: "Hello {name}",
    values: { name },
  }
);

✨plural✨
복수형 처리를 위해 사용된다.

import { plural } from "@lingui/macro";
const message = plural(count, {
  one: "# Book",
  other: "# Books",
});

// ↓ ↓ ↓ ↓ ↓ ↓

import { i18n } from "@lingui/core";
const message = i18n._(
  /*i18n*/ {
    id: "V/M0Vc",
    message: "{count, plural, one {# Book} other {# Books}}",
    values: { count },
  }
);

✨selectOrdinal✨
순서를 위해 사용된다.

import { selectOrdinal } from "@lingui/macro";
const message = selectOrdinal(count, {
  one: "#st",
  two: "#nd",
  few: "#rd",
  other: "#th",
});

// ↓ ↓ ↓ ↓ ↓ ↓

import { i18n } from "@lingui/core";
const message = i18n._(
  /*i18n*/ {
    id: "V8xI3w",
    message: "{count, selectOrdinal, one {#st} two {#nd} few {#rd} other {#th}}",
    values: { count },
  }
);

✨select✨
조건에 따라 메시지를 선택하는 경우 사용된다.

import { select } from "@lingui/macro";
const message = select(gender, {
  male: "he",
  female: "she",
  other: "they",
});

// ↓ ↓ ↓ ↓ ↓ ↓

import { i18n } from "@lingui/core";

const message = i18n._(
  /*i18n*/ {
    id: "VRptzI",
    message: "{gender, select, male {he} female {she} other {they}}",
    values: { gender },
  }
);

✨defineMessage or msg✨
나중에 사용할 메시지를 정의할 수 있게 해 주는데, 지연 번역에 주로 사용된다.

import { defineMessage } from "@lingui/macro";
const message = defineMessage`Hello World`;

// ↓ ↓ ↓ ↓ ↓ ↓

const message = /*i18n*/ {
  id: "mY42CM",
  message: "Hello World",
};

💗 JSX 매크로

✨Trans✨
정적 메시지, 변수를 포함한 메시지, 그리고 인라인 마크업이 있는 메시지를 처리하기 위해 사용된다.

id: 사용자 지정 메시지 ID
comment: 번역가를 위한 주석
context: 동일한 메시지를 다른 ID로 추출

import { Trans } from "@lingui/macro";
<Trans id="message.attachment_saved">Attachment {name} saved.</Trans>;

//사용자 지정 메시지 ID ↓ ↓ ↓ ↓ ↓ ↓

import { Trans } from "@lingui/react";
<Trans id="message.attachment_saved" message="Attachment {name} saved." />;

import { Trans } from "@lingui/macro";
<Trans context="direction">right</Trans>;
<Trans context="correctness">right</Trans>;

// context 사용시 다른 아이디를 부여함 ↓ ↓ ↓ ↓ ↓ ↓

import { Trans } from "@lingui/react";
<Trans id={"d1wX4r"} message="right" />;
<Trans id={"16eaSK"} message="right" />;

import { Trans } from "@lingui/macro";

<Trans>
  Read the <a href="/docs">docs</a>.
</Trans>;

// ↓ ↓ ↓ ↓ ↓ ↓

import { Trans } from "@lingui/macro";
<Trans id={"mk8bSG"} message="Read the <0>docs</0>." components={{ 0: <a href="/docs" /> }} />;

컴포넌트와 HTML 태그는 더미 인덱스 태그(<0></0>)로 대체된다.

• 사용자 정의 React 컴포넌트와 기본 HTML 태그 모두 지원.
• 컴포넌트의 props를 변경해도 번역이 깨지지 않음.
• 메시지가 전체 문장으로 추출된다.

🚨🤔🚨🧐 인덱스 태크란....?🚨🤔🚨🧐

<p>
  <Trans>
    See all <a href="/unread">unread messages</a>
    {" or "}
    <a onClick={markAsRead}>mark them</a> as read.
  </Trans>
</p>

만약 위의 코드를 extract 명령어를 돌려 추출하자면 아래와 같이 html 태그들은 인덱스 태그로 변경되어서 저장된다.

"See all <0>unread messages</0> or <1>mark them</1> as read."

나는 인덱스 태그( <0>, <1>)를 계속 번역 문장과 엮어서 생각을 해서 이해하기가 어려웠는데 🥲, 단순히 생각해서 태그/컴포넌트 표시하는 태그.. 문법으로 생각하니 이해하기가 쉬워졌다.

 

인덱스 태그를 사용하는 이유로 첫 번째 태그를 단순하게 관리 위함인데, 번역 과정에서 HTML이나 컴포넌트를 그대로 포함하면 번역가들이 혼란스러울 수 있기에, 태그나 컴포넌트는 숫자 인덱스로 표시하여 관리가 쉽도록 한다고 한다.
두 번째로는 코드 변경 시 번역에 영향이 없도록 하기 위해서이다. 인덱스 태그를 사용하였기에 해당 컴포넌트의 className이나 onClick 같은 속성을 변경하더라도 번역 메시지에는 영향을 주지 않는다. 번역 메시지는 오로지 인덱스로 태그 위치를 관리하기 때문에, 메시지를 재번역하거나 수정할 필요가 없다고 한다.

 

그럼 컴포넌트/태그가 있는 번역 메시지의 동작 방식은 위의 추출된 메시지에서 <0>과 <1>은 각각 <a href="/unread">와 <a onClick={markAsRead}>에 대응되고, Trans 매크로가 이 메시지를 렌더링 할 때, 인덱스 태그는 JSX로 되돌아가면서 원래 위치에 맞춰 컴포넌트와 속성들이 렌더링 된다.

 

✨Plural✨
복수형 형식으로 변환이 필요할 때 사용된다.

import { Plural } from "@lingui/macro";
<Plural value={numBooks} one="Book" other="Books" />;

// ↓ ↓ ↓ ↓ ↓ ↓

import { Trans } from "@lingui/react";
<Trans id={"is7n96"} message="{numBooks, plural, one {Book} other {Books}}" values={{ numBooks }} />;

#은 숫자 형식으로 사용된다.

import { Plural } from "@lingui/macro";

<Plural
  value={count}
  one="You and # other guest arrived"
  // when value >= 3
  other="You and # other guests arrived"
/>;

만약 id, context, 또는 comment가 필요하다면 <Trans> 매크로 내부에서 <Plural>을 사용하면 된다.

 

✨SelectOrdinal✨
특정 위치나 순서를 나타낼 때 사용된다.

import { SelectOrdinal } from "@lingui/macro";

// count == 1 -> 1st
// count == 2 -> 2nd
// count == 3 -> 3rd
// count == 4 -> 4th
<SelectOrdinal value={count} one="#st" two="#nd" few="#rd" other="#th" />;

✨Select✨
값에 따라 다른 문장을 표시해야 할 때 사용된다.

 import { Select } from "@lingui/macro";

// gender == "female"      -> Her book
// gender == "male"        -> His book
// gender == "non-binary"  -> Their book
<Select value={gender} _male="His book" _female="Her book" other="Their book" />;

other를 제외한 선택 항목들은 밑줄(_)로 시작해야 한다. 예: _male, _female.

3. React에서 Lingui 컴포넌트 사용하기

🔥 Trans로 감싸기
React 컴포넌트에서 가장 간단한 방법으로 번역을 적용할 수 있는 방법이다.

import { Trans } from "@lingui/macro";

function render() {
  return (
    <>
      <h1>
        <Trans>LinguiJS example</Trans>
      </h1>
      <p>
        <Trans>
          Hello <a href="/profile">{name}</a>.
        </Trans>
      </p>
    </>
  );
}

🔥 Trans 컴포넌트를 사용할 수 없는 경우도 발생하는데, 이때 t 매크로 사용이 필요하다.

✅ Trans 컴포넌트를 사용할 수 없는 경우

1. 컴포넌트 외부에서 텍스트 번역이 필요한 경우

2. 요소의 속성 관련한 텍스트 번역이 필요한 경우

t, plural, select, selectOrdinal 매크로는 기본적으로 글로벌 i18n 인스턴스를 사용하기에 대부분의 클라이언트 사이드 환경에서 잘 동작하지만, 서버사이드 렌더링(SSR)과 같은 특수한 상황에서는 특정 인스턴스를 명시적으로 사용하는 것이 더 좋다고 한다.

import { msg } from "@lingui/macro";
import { I18n } from "@lingui/core";

export function component () {

  const { i18n } = useLingui();

  alert(t(i18n)`토마토`);

  return (
    <div>...</div>
  )
}

🔥 변수 값에 따른 메시지 동적 선택

변수에 따라 다른 메시지를 선택해야 할 때도 있다. 예를 들어, API에서 받은 숫자 "status" 코드가 있을 때, 이 코드에 따라 현재 상태를 나타내는 메시지를 표시해야 한다면 "status"의 가능한 값들을 객체를 만들어, 번역을 지연 처리 방식으로 렌더링 할 수 있다.

import { msg } from "@lingui/macro";
import { useLingui } from "@lingui/react";

const statusMessages = {
  ["STATUS_OPEN"]: msg`Open`,
  ["STATUS_CLOSED"]: msg`Closed`,
  ["STATUS_CANCELLED"]: msg`Cancelled`,
  ["STATUS_COMPLETED"]: msg`Completed`,
};

export default function StatusDisplay({ statusCode }) {
  const { _ } = useLingui();
  return <div>{_(statusMessages[statusCode])}</div>;
}

 

++++++ 느낀 점 그리고 결론 ++++++

해당 라이브러리에서 자주 사용되는 매크로들과 리액트와 함께 사용하는 예시들만 간단히 정리해 보았는데, 잘 번역이 되도록 하기 위해서는 문법에 맞게 다양한 매크로를 잘 사용해야 한다고 느꼈다. 현재 회사에서는 다국어 프로젝트가 급하게 들어가게 되어서 문법에 맞는 세밀한 매크로 사용 대신 일단 번역이 되도록 하는 것에 집중이 되어 있는 상황이라.... 어색한 부분들이 많이 있을 것으로 예상되는데.. 결론 ->  라이브러리를 잘 사용하기란 쉽지 않은 것 같다. 🥲