Flutter 애플리케이션 국제화
목차
핵심 개념
Flutter는 flutter_localizations 및 intl 패키지를 통해 국제화(i18n)와 지역화(l10n)를 처리합니다. 표준 접근 방식은 App Resource Bundle(.arb) 파일을 사용하여 지역화된 문자열을 정의한 다음, 이를 타입 안전한 AppLocalizations 클래스로 컴파일하여 위젯 트리 내에서 안전하게 접근합니다.
설정 워크플로우
Flutter 프로젝트에서 국제화를 초기화할 때 아래 체크리스트를 복사하여 진행 상황을 추적하세요:
- 작업 진행
- 1.
pubspec.yaml에 종속성 추가 - 2.
generate플래그 활성화 - 3.
l10n.yaml설정 파일 생성 - 4.
MaterialApp또는CupertinoApp구성
- 1.
1. 종속성 추가
프로젝트에 필요한 지역화 패키지를 추가합니다. 터미널에서 다음 명령을 실행하세요:
flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any
pubspec.yaml의 dependencies 아래에 다음 내용이 포함되었는지 확인하세요:
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any
2. 코드 생성 활성화
pubspec.yaml을 열고 flutter 섹션 안에서 generate 플래그를 활성화하여 지역화 작업을 자동화합니다:
flutter:
generate: true
3. 설정 파일 생성
Flutter 프로젝트의 루트 디렉토리에 l10n.yaml이라는 새 파일을 만듭니다. 입력 디렉토리, 템플릿 파일, 출력 파일을 정의합니다:
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
4. 앱 진입점 구성
main.dart에서 생성된 지역화 모듈과 flutter_localizations 라이브러리를 임포트합니다. MaterialApp 또는 CupertinoApp에 델리게이트와 지원 로케일을 주입합니다.
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // synthetic-package가 false인 경우 경로 조정
// ... build 메서드 내부
return MaterialApp(
localizationsDelegates: const [
AppLocalizations.delegate,
GlobalMaterialLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
GlobalCupertinoLocalizations.delegate,
],
supportedLocales: const [
Locale('en'), // 영어
Locale('es'), // 스페인어
],
home: const MyHomePage(),
);
구현 워크플로우
지역화된 콘텐츠를 추가하거나 수정할 때 다음 워크플로우를 따르세요.
1. ARB 파일 정의
- 새 콘텐츠를 만드는 경우: 템플릿 파일(
lib/l10n/app_en.arb)에 기본 문자열을 추가합니다. 문맥 설명도 포함하세요. - 기존 콘텐츠를 수정하는 경우: 지원되는 모든
.arb파일에서 해당 키를 찾아 값을 업데이트합니다.
{
"helloWorld": "Hello World!",
"@helloWorld": {
"description": "The conventional newborn programmer greeting"
}
}
다른 로케일용 파일(예: app_es.arb)도 만듭니다:
{
"helloWorld": "¡Hola Mundo!"
}
2. 지역화 클래스 생성
다음 명령을 실행하여 코드 생성을 트리거합니다:
flutter pub get
피드백 루프: 실행기 실행 -> 터미널 출력에서 ARB 구문 오류 확인 -> 누락된 쉼표나 불일치하는 플레이스홀더 수정 -> flutter pub get 재실행.
3. 지역화된 문자열 사용
위젯 트리에서 AppLocalizations.of(context)를 사용하여 지역화된 문자열에 접근합니다. 이 메서드를 호출하는 위젯은 MaterialApp의 하위 위젯이어야 합니다.
Text(AppLocalizations.of(context)!.helloWorld)
고급 서식
동적 데이터, 복수형, 조건부 선택을 위해 플레이스홀더를 사용합니다.
플레이스홀더
중괄호 안에 매개변수를 정의하고 메타데이터 객체에 해당 타입을 지정합니다.
"hello": "Hello {userName}",
"@hello": {
"description": "A message with a single parameter",
"placeholders": {
"userName": {
"type": "String",
"example": "Bob"
}
}
}
복수형(Plurals)
plural 구문을 사용하여 수량에 따른 문자열 변형을 처리합니다. other 케이스는 필수입니다.
"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
"@nWombats": {
"description": "A plural message",
"placeholders": {
"count": {
"type": "num",
"format": "compact"
}
}
}
선택문(Selects)
select 구문을 사용하여 성별 텍스트와 같은 조건부 문자열을 처리합니다.
"pronoun": "{gender, select, male{he} female{she} other{they}}",
"@pronoun": {
"description": "A gendered message",
"placeholders": {
"gender": {
"type": "String"
}
}
}
예제
완전한 l10n.yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
use-escaping: true
완전한 위젯 구현
import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
class GreetingWidget extends StatelessWidget {
final String userName;
final int notificationCount;
const GreetingWidget({
super.key,
required this.userName,
required this.notificationCount,
});
@override
Widget build(BuildContext context) {
final l10n = AppLocalizations.of(context)!;
return Column(
children: [
Text(l10n.hello(userName)),
Text(l10n.nWombats(notificationCount)),
],
);
}
}