Flutter 현지화: ARB 파일, intl, gen-l10n 완벽 해설

현지화 생성기는 하나만 사용하고 입력 및 출력 위치를 명시하세요. 아래 예제는 자체 SDK 제약 조건과 일반적인 프로젝트 구성을 갖춘 기존 Flutter 애플리케이션을 전제로 합니다.

관련 항목을 pubspec.yaml에 병합하세요. dependencies 또는 flutter 섹션을 중복해서 만들지 마세요.

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

flutter pub get으로 종속성을 해결하세요. intl: any 항목은 공식 설정 패턴을 따르므로 종속성 해결 과정에서 Flutter SDK와 호환되는 버전이 선택됩니다. 애플리케이션의 lockfile과 일반적인 종속성 검토 프로세스는 그대로 유지하세요.

프로젝트 루트에 l10n.yaml을 생성하세요.

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

SDK별 설정은 최신 Flutter 국제화 가이드를 참고하세요. 최신 프로세스에서는 생성된 현지화 파일이 애플리케이션 소스 트리에 위치합니다. 이 예제는 lib/l10n에서 가져옵니다. 예전의 합성 package:flutter_gen import를 새 설정에 복사하지 마세요. 생성 소스 마이그레이션 안내를 참고하세요.

lib/l10n/app_en.arb를 생성하세요.

{
  "@@locale": "en",
  "appTitle": "Reading room",
  "@appTitle": {
    "description": "Title of the sample reading application"
  },
  "welcomeName": "Welcome, {name}",
  "@welcomeName": {
    "description": "Greeting on the home screen",
    "placeholders": {
      "name": {"type": "String", "example": "Sam"}
    }
  },
  "savedBooks": "{count, plural, =0{No saved books} one{1 saved book} other{{count} saved books}}",
  "@savedBooks": {
    "description": "Number of books saved to the user's library",
    "placeholders": {
      "count": {"type": "int"}
    }
  },
  "readingState": "{state, select, active{Reading now} paused{Reading paused} other{Ready to read}}",
  "@readingState": {
    "description": "Reading status; state is active, paused or another value",
    "placeholders": {
      "state": {"type": "String"}
    }
  }
}

lib/l10n/app_es.arb를 생성하세요.

{
  "@@locale": "es",
  "appTitle": "Sala de lectura",
  "welcomeName": "Te damos la bienvenida, {name}",
  "savedBooks": "{count, plural, =0{No hay libros guardados} one{1 libro guardado} other{{count} libros guardados}}",
  "readingState": "{state, select, active{Leyendo ahora} paused{Lectura en pausa} other{Todo listo para leer}}"
}

템플릿에는 생성기가 사용하는 플레이스홀더 메타데이터가 들어 있습니다. 현지화된 파일은 메시지 키, 플레이스홀더 이름, select 식별자를 유지하면서 사용자에게 표시되는 문구만 바꿉니다. 이 스페인어 예제는 작동 방식을 보여 주기 위한 것이며, 프로덕션 언어는 실제 제품 맥락에서 원어민 검토를 받아야 합니다.

리소스를 추가하거나 변경한 후에는 flutter gen-l10n을 실행하세요. 생성기 오류는 조치가 필요한 리소스 문제로 간주하고, 파일을 릴리스에 통합하기 전에 해결하세요.

생성이 끝나면 다음 예제를 lib/main.dart에 넣으세요.

import 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';

void main() => runApp(const ReadingApp());

class ReadingApp extends StatelessWidget {
  const ReadingApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const ReadingHome(),
    );
  }
}

class ReadingHome extends StatelessWidget {
  const ReadingHome({super.key});

  @override
  Widget build(BuildContext context) {
    final messages = AppLocalizations.of(context)!;
    return Scaffold(
      appBar: AppBar(title: Text(messages.appTitle)),
      body: Padding(
        padding: const EdgeInsetsDirectional.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(messages.welcomeName('Sam')),
            Text(messages.savedBooks(3)),
            Text(messages.readingState('active')),
          ],
        ),
      ),
    );
  }
}

생성된 API는 일반 메시지와 인수가 있는 메시지의 차이를 코드에서 명확히 보여 줍니다. appTitle은 값으로 접근하고, welcomeName, savedBooks, readingState는 메시지를 만드는 데 필요한 값을 전달받습니다.

선택하기 전에 최신 easy_localization 문서와 GetX 문서를 검토하세요. 실제 메시지로 대체 동작, 매개변수, 복수형 범주, 추출 프로세스를 테스트하세요. 영어 문자열에 편리한 API라고 해서 출시하려는 모든 언어를 지원한다는 보장은 없습니다.

intl은 경쟁 관계에 있는 번역 관리 플랫폼이 아닙니다. 현지화 프로세스에서 사용하는 국제화 유틸리티를 제공합니다. gen-l10n은 ARB 리소스에서 애플리케이션 접근자를 생성합니다. 별도의 intl_utils 패키지도 현지화 코드를 생성하지만, 2026년 10월 30일 확인 당시 패키지 페이지에 지원 중단으로 표시되어 있었습니다. 새 프로젝트에 도입하기 전에 유지 관리 상태를 확인하세요.

실용적인 테스트 매트릭스를 활용하세요.

Flutter 웹 FAQ는 Flutter가 애플리케이션 경험에 중점을 둔다고 설명하며, 텍스트가 많은 정적 웹 콘텐츠에는 문서 중심 접근 방식을 권장합니다. 마케팅, 도움말, 편집 페이지가 자연 검색에서 성과를 내야 한다면 별도의 HTML 기반 페이지를 고려하세요.

앱과 이러한 공개 페이지의 용어를 일치시키세요. 두 화면이 서로 다른 렌더링 시스템을 사용하더라도, 검색으로 유입된 방문자가 현지화된 랜딩 페이지에서 애플리케이션으로 이동한 후에도 기능 이름을 알아볼 수 있어야 합니다.

Smartcat에서 문서화한 소프트웨어 프로젝트 형식에는 JSON, YAML, Android XML, iOS .strings, LocJSON 가져오기가 포함됩니다. 이 가이드에서 검토한 문서로는 ARB 기본 지원이나 테스트를 거친 ARB-JSON 변환 프로세스를 확인할 수 없습니다. 파일 확장자를 바꾼다고 호환성이 입증된다고 가정하지 마세요. 소프트웨어 프로젝트 문서를 참고하세요.

다음 내용은 이미 테스트된 커넥터 방법이 아니라 구현 팀과 함께 진행할 검증 절차 제안으로 활용하세요.