지금까지 만든 앱의 글자는 전부 코드에 직접 적혀 있다. Text('안녕하세요')처럼. 영어 사용자를 위한 버전이 필요해지면 가장 먼저 떠오르는 방법은 이렇다.

Widget build(BuildContext context) {
  final isKorean = Localizations.localeOf(context).languageCode == 'ko';
  return Text(isKorean ? '안녕하세요' : 'Hello'); // 문구마다 이런 분기를 단다
}

문구가 열 개일 때는 버틴다. 백 개가 되고, 일본어를 추가하는 순간 모든 Text를 다시 열어서 분기를 고쳐야 한다. 번역가에게 "이 파일만 번역해 주세요"라고 맡길 수도 없다. 문구는 코드에서 떼어내서 언어별 파일에 따로 모아두는 것이 방법이다. 이걸 지역화(localization, l10n)라고 한다.

1단계: 설치와 설정

flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any

pubspec.yaml의 flutter: 아래에 자동 생성을 켠다.

flutter:
  generate: true

프로젝트 맨 위 폴더에 l10n.yaml을 만든다.

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

• arb-dir: 번역 파일을 둘 폴더다
• template-arb-file: 기준이 되는 언어 파일이다. 다른 언어 파일은 이 파일의 키를 따라간다

2단계: 번역 파일(ARB) 쓰기

lib/l10n/app_en.arb는 JSON 모양이다. 키가 이름이고 값이 문구다.

{
  "appTitle": "My App",
  "hello": "Hello, {name}!",
  "@hello": {
    "placeholders": {
      "name": { "type": "String" }
    }
  },
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "placeholders": {
      "count": { "type": "int" }
    }
  }
}

lib/l10n/app_ko.arb는 같은 키에 한국어 문구를 쓴다. 파일 이름의 _ko가 언어를 가리킨다.

{
  "appTitle": "내 앱",
  "hello": "{name}님, 안녕하세요!",
  "itemCount": "{count}개"
}

• {name}: 문구 속에 값을 끼워 넣는 자리(placeholder)다. @hello에서 그 타입을 알려준다
• {count, plural, ...}: 개수에 따라 문장이 달라지는 영어 같은 언어를 위한 복수형 문법이다. 한국어는 단수와 복수 구분이 없어서 {count}개로 충분하다
• 언어를 더 추가하려면 app_ja.arb처럼 파일만 하나 더 만든다

3단계: 코드 생성과 연결

flutter gen-l10n

이 명령이 ARB 파일을 읽어서 AppLocalizations 클래스를 만든다. 앞서 JSON 글에서 본 코드 생성과 같은 발상이다. 이제 MaterialApp에 연결한다.

MaterialApp(
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,
  home: const HomePage(),
)

문구는 AppLocalizations.of(context)로 꺼낸다.

@override
Widget build(BuildContext context) {
  final l10n = AppLocalizations.of(context)!;
  return Column(
    children: [
      Text(l10n.appTitle),
      Text(l10n.hello('홍길동')),   // placeholder는 함수의 인자가 된다
      Text(l10n.itemCount(3)),
    ],
  );
}

키 이름이 곧 메서드 이름이라서 오타를 내면 컴파일 때 빨간 줄이 뜬다. 문자열 키로 찾던 방식과의 가장 큰 차이다. 기기의 언어가 한국어면 한국어, 영어면 영어 문구가 나온다. 지원하지 않는 언어는 템플릿 파일의 첫 번째 지원 언어로 돌아간다.

of(context)는 Theme.of(context)와 같은 방식이라, MaterialApp 아래의 위젯에서만 쓸 수 있다. MaterialApp을 만드는 build의 context로 부르면 위로 올라가도 못 찾는 문제가 여기서도 똑같이 생긴다. 생성된 파일을 import하는 경로는 Flutter 버전에 따라 다르니, flutter gen-l10n을 실행한 뒤 에디터의 자동 import를 따른다. 에디터가 !가 필요 없다고 알려주면 지운다.

삽질 포인트 1: AppLocalizations를 찾을 수 없다

가장 흔한 에러다. 원인은 보통 세 가지다.

• flutter: generate: true를 pubspec.yaml에 안 넣었다
• l10n.yaml의 경로가 틀렸거나, ARB 파일이 arb-dir에 정한 폴더에 없다
• 생성 명령을 아직 안 돌렸다

flutter gen-l10n이나 flutter pub get을 한 번 돌리면 풀리는 경우가 많다. ARB 파일을 고친 뒤에도 다시 생성해야 코드에 반영된다. 새 키를 추가했는데 l10n.xxx가 빨간 줄이라면 생성을 안 한 것이다.

삽질 포인트 2: iOS에서는 지원 언어를 한 번 더 알려야 한다

Flutter 쪽 설정만으로는 iOS 시스템이 "이 앱은 한국어를 지원한다"고 인식하지 못하는 경우가 있다. ios/Runner/Info.plist의 CFBundleLocalizations에 지원하는 언어 코드(en, ko 등)를 적어준다.

날짜와 숫자도 언어에 맞춘다

문구만 바꾼다고 끝이 아니다. 같은 날짜도 나라마다 표기가 다르다. intl 패키지가 이를 맞춰준다.

import 'package:intl/intl.dart';

final date = DateFormat.yMMMd('ko').format(DateTime.now());      // 2026년 10월 8일
final price = NumberFormat.currency(locale: 'ko_KR', symbol: '₩').format(12000); // ₩12,000

날짜와 금액을 toString()으로 직접 이어 붙이지 않고 포맷터를 거친다.

앱 안에서 언어 바꾸기

기기 설정과 다르게 앱 안에서 언어를 고르게 하려면 테마 글의 themeMode와 같은 방식이다. MaterialApp의 locale에 값을 넣고 setState로 바꾼다. 고른 값은 로컬 저장소 글처럼 shared_preferences에 저장해서, 다시 켜도 유지한다.

MaterialApp(
  locale: _locale, // null이면 기기 언어를 따른다
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,
)

앱 아이콘 바꾸기: flutter_launcher_icons

기본으로 들어 있는 Flutter 로고 아이콘을 내 아이콘으로 바꿀 차례다. 안드로이드는 여러 크기의 이미지를 mipmap 폴더마다, iOS는 Assets.xcassets에 크기별로 넣어야 해서 손으로 하면 번거롭다. 이미지 한 장으로 나머지를 만들어주는 flutter_launcher_icons를 쓴다.

flutter pub add dev:flutter_launcher_icons

pubspec.yaml에 설정을 쓴다.

flutter_launcher_icons:
  android: true
  ios: true
  image_path: "assets/icon/icon.png"
  adaptive_icon_background: "#FFFFFF"
  adaptive_icon_foreground: "assets/icon/icon_foreground.png"
  remove_alpha_ios: true

dart run flutter_launcher_icons

• image_path: 원본 이미지다. 1024×1024 정도의 큰 정사각형 PNG를 쓴다
• adaptive_icon_*: 안드로이드 8 이상이 기기마다 아이콘 모양(동그라미, 둥근 사각형)을 다르게 자르는 방식이다. 배경과 앞의 그림을 따로 준다. 그림은 가장자리에 붙이지 않고 가운데에 여유 있게 둔다
• remove_alpha_ios: iOS 아이콘은 투명 영역이 있으면 App Store가 받지 않는다. 투명한 부분을 지워서 만들어준다

flavor별로 아이콘을 나눌 때는 flutter_launcher_icons-<flavor>.yaml처럼 flavor 이름을 붙인 설정 파일을 쓴다. 아이콘을 바꿨는데 기기에 그대로면 앱을 지우고 다시 설치해 본다.

스플래시 화면 바꾸기: flutter_native_splash

앱을 켜고 Flutter 화면이 뜨기까지 잠깐 흰 화면이 보인다. 이 구간에 보이는 게 스플래시(시작) 화면이다. Flutter 위젯이 아니라 운영체제가 앱 시작 때 보여주는 네이티브 화면이라서, Dart 코드로는 바꿀 수 없고 flutter_native_splash가 네이티브 설정을 대신 고쳐준다.

flutter pub add dev:flutter_native_splash

flutter_native_splash:
  color: "#FFFFFF"
  image: assets/splash/logo.png
  color_dark: "#000000"
  image_dark: assets/splash/logo_dark.png
  android_12:
    color: "#FFFFFF"
    image: assets/splash/logo_android12.png

dart run flutter_native_splash:create

• color, image: 배경색과 가운데 로고다
• color_dark, image_dark: 다크 모드일 때 쓰는 값이다. 테마 글의 다크 모드와 맞춘다
• android_12: 안드로이드 12부터는 시스템이 스플래시를 직접 그린다. 앱 아이콘을 원 안에 보여주는 방식이라, 따로 설정해야 의도한 모양이 나온다

스플래시는 Flutter가 준비되는 순간 사라진다. 서버에서 첫 데이터를 받을 때까지 더 보여주고 싶다면 FlutterNativeSplash.preserve(...)로 붙잡아 두었다가 준비가 끝나면 FlutterNativeSplash.remove()로 지운다. 너무 오래 붙잡아 두면 사용자가 앱이 멈춘 걸로 느끼니 주의한다.

Android, iOS와 비교하면

// Compose - 문자열 리소스
Text(stringResource(R.string.hello, name))
// res/values/strings.xml, res/values-ko/strings.xml

// SwiftUI - String Catalog
Text("hello \(name)")
// Localizable.xcstrings에 언어별 문구를 모은다

• 문구 모으는 곳: Flutter lib/l10n/app_*.arb / Android res/values-ko/strings.xml / iOS Localizable.xcstrings(String Catalog)
• 꺼내 쓰기: Flutter AppLocalizations.of(context)!.hello(name) / Compose stringResource(R.string.hello, name) / SwiftUI Text("hello \(name)")
• 오타 방어: Flutter와 Android는 생성된 이름이라 컴파일 때 잡힘 / SwiftUI 문자열 키는 String Catalog가 확인
• 아이콘: Flutter flutter_launcher_icons / Android Studio Image Asset / Xcode Assets
• 스플래시: Flutter flutter_native_splash / Android 12 이상 SplashScreen API / iOS LaunchScreen

Android의 strings.xml과 ARB는 같은 발상이다. 다만 Flutter의 ARB는 세 플랫폼이 한 파일을 공유한다는 게 강점이다. 아이콘과 스플래시는 결국 각 플랫폼의 네이티브 설정을 바꾸는 일이라, 도구가 대신 해줄 뿐 안에서 하는 일은 같다.

정리

• 문구를 코드에 직접 적고 분기하면 언어를 늘릴 때마다 모든 곳을 고쳐야 하므로, ARB 파일에 언어별로 모은다
• flutter_localizations, intl을 설치하고 flutter: generate: true, l10n.yaml, lib/l10n/app_en.arb를 갖춘 뒤 flutter gen-l10n으로 AppLocalizations를 만든다
• MaterialApp에 localizationsDelegates와 supportedLocales를 넣고, AppLocalizations.of(context)!.키()로 꺼내서 키 오타를 컴파일 때 잡는다
• AppLocalizations를 못 찾으면 generate: true, l10n.yaml, ARB 폴더, 생성 명령을 확인하고, ARB를 고치면 다시 생성한다. iOS는 CFBundleLocalizations도 챙긴다
• 날짜와 금액은 intl의 DateFormat, NumberFormat으로 언어에 맞춘다
• 아이콘은 flutter_launcher_icons로 이미지 한 장에서 만들고 iOS는 투명 영역을 없애며, 스플래시는 flutter_native_splash로 바꾼다. 스플래시는 Flutter 위젯이 아니라 네이티브 화면이다

다음 글에서는 같은 앱을 개발용과 운영용으로 나눠서 만드는 flavor를 다뤄보겠다.