Communitygithub.com

Flutter 국제화(i18n) 스킬

Flutter 프로젝트에 `flutter_localizations` 및 `intl` 종속성을 추가하고, `pubspec.yaml`에 `generate: true`를 활성화하며, `l10n.yaml` 설정 파일을 생성하는 스킬입니다. 새 Flutter 프로젝트에서 지역화(l10n) 지원을 초기화할 때 사용하세요.

Flutter 국제화(i18n) 스킬란 무엇인가요?

이 스킬은 Flutter 애플리케이션에 국제화(i18n) 및 지역화(l10n) 지원을 설정하는 방법을 단계별로 안내합니다. `flutter_localizations`와 `intl` 패키지를 이용하며, ARB(App Resource Bundle) 파일로 문자열을 정의한 후 자동 생성된 타입 안전한 `AppLocalizations` 클래스를 통해 위젯 트리에서 접근할 수 있도록 합니다. 설정 워크플로우(종속성 추가, `generate` 플래그 활성화, `l10n.yaml` 생성, `MaterialApp` 설정)와 구현 워크플로우(ARB 파일 정의, 코드 생성, 지역화된 문자열 사용)를 모두 다루며, 고급 서식(placeholders, plurals, selects) 예제와 함께 완전한 위젯 구현 예시를 제공합니다. 이 스킬은 모든 Flutter 프로젝트에 적용 가능하며, Flutter CLI와 Dart 언어의 기본 지식을 가진 개발자라면 누구나 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/dbillion/hermes-skills-public/tree/HEAD/skills-external/flutter-setup-localization

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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. 종속성 추가

프로젝트에 필요한 지역화 패키지를 추가합니다. 터미널에서 다음 명령을 실행하세요:

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)),
      ],
    );
  }
}

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

dbillion/hermes-skills-public

Edit an existing image based on a text prompt.

dbillion/hermes-skills-public

Expert in video composition, editing, and format conversion. Use when the user wants to generate high-quality video, overlay images on video, concatenate clips, create GIFs, or sync audio to video using mcp-avtool-go and mcp-veo-go.

dbillion/hermes-skills-public

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

dbillion/hermes-skills-public

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

dbillion/hermes-skills-public

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.

dbillion/hermes-skills-public

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

관련 스킬