생성:2024-12-02마지막 업데이트:2025-06-29

이 문서를 원하는 AI 어시스턴트에 참조하세요ChatGPT Claude DeepSeek Google AI mode Gemini Perplexity Mistral Grok

이 페이지와 원하는 AI 어시스턴트를 사용하여 문서를 요약합니다

버전 기록

"초기 이력"
v5.5.102025. 6. 29.

이 페이지의 콘텐츠는 AI를 사용하여 번역되었습니다.

영어 원본 내용의 최신 버전을 보기

문서 수정

이 문서를 개선할 아이디어가 있으시면 GitHub에 풀 리퀘스트를 제출하여 자유롭게 기여해 주세요.

문서에 대한 GitHub 링크

복사

문서의 Markdown을 클립보드에 복사

문서: `express-intlayer`의 `t` 함수

Name: Intlayer
Author: Intlayer

express-intlayer 패키지의 t 함수는 Express 애플리케이션에서 지역화된 응답을 제공하는 핵심 유틸리티입니다. 사용자의 선호 언어에 따라 동적으로 콘텐츠를 선택하여 국제화(i18n)를 간소화합니다.

개요

t 함수는 주어진 언어 집합에 대한 번역을 정의하고 검색하는 데 사용됩니다. 클라이언트의 요청 설정(예: Accept-Language 헤더)을 기반으로 반환할 적절한 언어를 자동으로 결정합니다. 선호하는 언어가 없을 경우, 구성에 지정된 기본 로케일로 우아하게 대체됩니다.

주요 기능

동적 지역화: 클라이언트에 가장 적합한 번역을 자동으로 선택합니다.
기본 로케일로 대체: 클라이언트가 선호하는 언어를 사용할 수 없을 경우 기본 로케일로 대체하여 사용자 경험의 연속성을 보장합니다.
경량 및 고속: 고성능 애플리케이션을 위해 설계되어 최소한의 오버헤드를 보장합니다.
엄격 모드 지원: 선언된 로케일을 엄격히 준수하도록 하여 신뢰할 수 있는 동작을 보장합니다.

함수 시그니처

t(translations: Record<string, string>): string;

매개변수

translations: 키는 로케일 코드(예: en, fr, es-MX)이고 값은 해당 번역 문자열인 객체입니다.

반환값

클라이언트가 선호하는 언어로 된 내용을 나타내는 문자열입니다.

국제화 요청 핸들러 로딩

express-intlayer에서 제공하는 국제화 기능이 올바르게 작동하도록 하려면, Express 애플리케이션의 시작 부분에서 반드시 국제화 미들웨어를 로드해야 합니다. 이렇게 하면 t 함수가 활성화되고, 로케일 감지 및 번역 처리가 제대로 이루어집니다.

애플리케이션 내 모든 라우트가 국제화의 혜택을 받을 수 있도록 app.use(intlayer()) 미들웨어를 모든 라우트보다 먼저 배치하세요:

import express, { type Express } from "express";
import { intlayer } from "express-intlayer";

const app: Express = express();

// 국제화 요청 핸들러 로드
app.use(intlayer());

// 미들웨어 로드 후 라우트 정의
app.get("/", (_req, res) => {
  res.send(
`express-intlayer`에서 제공하는 국제화 기능이 올바르게 작동하려면, Express 애플리케이션의 시작 부분에서 반드시 국제화 미들웨어를 로드해야 합니다. 이렇게 하면 `t` 함수가 활성화되고, 로케일 감지 및 번역 처리가 제대로 이루어집니다.

애플리케이션의 모든 라우트가 국제화 기능을 활용할 수 있도록 `app.use(intlayer())` 미들웨어를 **모든 라우트보다 먼저** 배치하세요:

```typescript {7} fileName="src/index.ts" codeFormat="typescript"
import express, { type Express } from "express";
import { intlayer } from "express-intlayer";

const app: Express = express();

// 국제화 요청 핸들러 로드
app.use(intlayer());

// 미들웨어 로드 후 라우트 정의
app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
    })
  );
});

이 작업이 필요한 이유

로케일 감지: intlayer 미들웨어는 요청 헤더, 쿠키 또는 기타 설정된 방법을 통해 사용자의 선호 로케일을 감지합니다.
번역 컨텍스트 설정: t 함수가 올바르게 작동할 수 있도록 필요한 컨텍스트를 설정하여 정확한 언어로 번역을 반환합니다.
오류 방지: 이 미들웨어가 없으면 t 함수를 사용할 때 필요한 로케일 정보가 없어 런타임 오류가 발생합니다.

사용 예제

기본 예제

// 미들웨어를 로드한 후 라우트를 정의합니다 app.get("/", (_req, res) => { res.send( t({ en: "Hello, World!", fr: "Bonjour le monde!", es: "¡Hola, Mundo!", }) ); });


### 왜 이것이 필요한가

- **로케일 감지**: `intlayer` 미들웨어는 헤더, 쿠키 또는 기타 구성된 방법을 기반으로 사용자의 선호 로케일을 감지하기 위해 들어오는 요청을 처리합니다.
- **번역 컨텍스트**: `t` 함수가 올바르게 작동할 수 있도록 필요한 컨텍스트를 설정하여 번역이 올바른 언어로 반환되도록 보장합니다.
- **오류 방지**: 이 미들웨어가 없으면 `t` 함수를 사용할 때 필요한 로케일 정보가 없기 때문에 런타임 오류가 발생합니다.

---

## 사용 예제

### 기본 예제

다양한 언어로 현지화된 콘텐츠 제공:

```typescript fileName="src/index.ts" codeFormat="typescript"
app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

클라이언트 요청:

Accept-Language: fr 헤더를 가진 클라이언트는 Bienvenue!를 받습니다.
Accept-Language: es를 가진 클라이언트는 ¡Bienvenido!를 받습니다.
Accept-Language: de를 가진 클라이언트는 Welcome! (기본 로케일)을 받습니다.

오류 처리

여러 언어로 오류 메시지를 제공합니다:

app.get("/error", (_req, res) => {
  res.status(500).send(
    t({
      en: "An unexpected error occurred.",
      fr: "Une erreur inattendue s'est produite.",
      es: "Ocurrió un error inesperado.",
    })
  );
});

로케일 변형 사용하기

로케일별 변형에 대한 번역을 지정하세요:

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "안녕, 친구!",
      fr: "안녕하세요!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "안녕하세요!",
      "en-GB": "안녕, 친구!",
      fr: "안녕하세요!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

고급 주제

폴백 메커니즘

선호하는 로케일을 사용할 수 없는 경우, t 함수는 구성에서 정의된 기본 로케일로 폴백합니다:

import { Locales, type IntlayerConfig } from "intlayer";

const config = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

예를 들어:

defaultLocale가 Locales.CHINESE로 설정되어 있고 클라이언트가 Locales.DUTCH를 요청하면, 반환되는 번역은 Locales.CHINESE 값으로 기본 설정됩니다.
defaultLocale가 정의되어 있지 않으면, t 함수는 Locales.ENGLISH 값을 기본으로 사용합니다.

엄격 모드 적용

t 함수를 구성하여 선언된 로케일을 엄격하게 준수하도록 설정할 수 있습니다:

테이블의 모든 내용 표시

테이블을 모달로 열어 모든 데이터를 명확하게 확인

모드	동작
`strict`	선언된 모든 로케일에 번역이 제공되어야 합니다. 누락된 로케일이 있으면 오류가 발생합니다.
`inclusive`	선언된 로케일은 번역을 반드시 포함해야 합니다. 누락된 로케일은 경고를 발생시키지만 허용됩니다.
`loose`	선언되지 않은 로케일이라도 존재하는 모든 로케일을 허용합니다.

구성 예시:

import { type IntlayerConfig } from "intlayer";

const config = {
  // ... 기존 구성 유지
  internationalization: {
    // ... 기존 국제화 구성 유지
    strictMode: "strict", // 엄격 모드 적용
  },
} satisfies IntlayerConfig;

export default config;

TypeScript 통합

t 함수는 TypeScript와 함께 사용할 때 타입 안전성을 제공합니다. 타입 안전한 번역 객체를 정의하세요:

import { type LanguageContent } from "express-intlayer";

const translations: LanguageContent<string> = {
  en: "Good morning!",
  fr: "Bonjour!",
  es: "¡Buenos días!",
};

app.get("/morning", (_req, res) => {
  res.send(t(translations));
});

일반적인 오류 및 문제 해결