Skip to main content

Flutter स्थानीयकरण की संपूर्ण गाइड

ARB फ़ाइलों से लेकर RTL समर्थन तक: easy_localization से अपने Flutter ऐप का स्थानीयकरण करें, हर भाषा के बहुवचन संभालें और AI से अनुवाद स्वचालित करें।

1

easy_localization इंस्टॉल करें

अपने pubspec.yaml में easy_localization पैकेज जोड़ें। यह सबसे लोकप्रिय Flutter i18n पैकेज है, जो ARB/JSON फ़ाइलों, बहुवचन और context extensions का समर्थन करता है। तारीखों, संख्याओं और टेक्स्ट की दिशा की locale-aware फ़ॉर्मैटिंग के लिए SDK से flutter_localizations भी जोड़ें।

easy_localization संक्षिप्त रूप से अनुवाद पाने के लिए context.tr() और 'key'.tr() जैसे context extensions देता है। यह डेवलपमेंट के दौरान locale लोडिंग, स्थायी स्टोरेज और अनुवाद फ़ाइलों की hot-reloading संभालता है।
pubspec.yaml
dependencies:
  easy_localization: ^3.0.7
  flutter_localizations:
    sdk: flutter
2

ARB अनुवाद फ़ाइलें बनाएँ

Application Resource Bundle (ARB) फ़ाइलें Flutter के स्थानीयकरण का मानक फ़ॉर्मैट हैं। हर फ़ाइल में key-value जोड़ियाँ होती हैं और वैकल्पिक metadata में placeholders, बहुवचन नियमों और अनुवादकों के लिए संदर्भ का विवरण दिया जा सकता है। अपनी assets/translations डायरेक्टरी में हर locale के लिए एक फ़ाइल बनाएँ।

assets/translations/en.arb
{
  "@@locale": "en",
  "appTitle": "My App",
  "@appTitle": {
    "description": "The title of the application"
  },
  "greeting": "Hello, {name}!",
  "@greeting": {
    "description": "Greeting with user name",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  },
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items in the cart",
    "placeholders": {
      "count": {
        "type": "num",
        "format": "compact"
      }
    }
  }
}
@ से शुरू होने वाली keys (जैसे @greeting) metadata होती हैं—वे अपने ऊपर वाली string का विवरण देती हैं। अनुवादकों को सटीक अनुवाद तैयार करने में मदद देने के लिए placeholder के प्रकार और उदाहरण शामिल करें। ये metadata keys runtime पर हटा दी जाती हैं और इनसे कोई अतिरिक्त overhead नहीं जुड़ता।
3

ऐप कॉन्फ़िगर करें

अपने ऐप को EasyLocalization widget में wrap करें। यह locale की state संभालता है, आपकी asset फ़ाइलों से अनुवाद लोड करता है और MaterialApp के लिए आवश्यक locale delegates उपलब्ध कराता है। तीन आवश्यक delegate properties हैं: localizationsDelegates, supportedLocales और locale—ये सभी context extensions के माध्यम से उपलब्ध हैं।

lib/main.dart
import 'package:flutter/material.dart';
import 'package:easy_localization/easy_localization.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await EasyLocalization.ensureInitialized();

  runApp(
    EasyLocalization(
      supportedLocales: [
        Locale('en'),
        Locale('ar'),
        Locale('ja'),
        Locale('de'),
      ],
      path: 'assets/translations',  // Path to your ARB/JSON files
      fallbackLocale: Locale('en'),
      child: MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: context.localizationDelegates,
      supportedLocales: context.supportedLocales,
      locale: context.locale,
      home: HomePage(),
    );
  }
}
"Easy Localization not initialized"—इस error का अर्थ है कि आप runApp() से पहले EasyLocalization.ensureInitialized() को call करना भूल गए। इसे WidgetsFlutterBinding.ensureInitialized() के बाद और runApp() से पहले await करना आवश्यक है।
4

Widgets का अनुवाद करें

किसी भी widget में अनूदित टेक्स्ट पाने के लिए string keys पर .tr() extension method इस्तेमाल करें। बहुवचन के लिए count value के साथ .plural() इस्तेमाल करें। easy_localization string extension syntax ('key'.tr()) और context method syntax (context.tr('key')) दोनों देता है।

lib/widgets/home_page.dart
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('appTitle'.tr()),   // Simple key
      ),
      body: Column(
        children: [
          // String with variable interpolation
          Text('greeting'.tr(args: ['Alice'])),

          // Named arguments
          Text('greeting'.tr(namedArgs: {'name': 'Alice'})),

          // Plural form
          Text('itemCount'.plural(3)),
        ],
      ),
    );
  }
}
अगर अनुवादित टेक्स्ट की जगह raw keys लौटती हैं, तो जाँचें: 1) EasyLocalization widget आपके MaterialApp को wrap करता हो, इसका उलटा नहीं। 2) आपकी अनुवाद फ़ाइलें pubspec.yaml में assets के अंतर्गत घोषित हों। 3) EasyLocalization में दिया गया फ़ाइल path आपकी वास्तविक directory structure से मेल खाता हो।
5

बहुवचन और Variables संभालें

Flutter बहुवचन के लिए ICU MessageFormat इस्तेमाल करता है—यही मानक iOS, Android और वेब में भी इस्तेमाल होता है। अपनी ARB फ़ाइलों में {count, plural, ...} सिंटैक्स से बहुवचन रूप तय करें। CLDR के बहुवचन नियमों के आधार पर हर भाषा को अपने अलग रूपों की आवश्यकता होती है। अरबी में 6, रूसी में 4 और जापानी में 1 रूप होता है।

Plural forms by language
// English: 3 useful forms (=0, =1, other)
"itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}"

// Arabic: 6 forms (=0, =1, =2, few, many, other)
"itemCount": "{count, plural, =0{لا عناصر} =1{عنصر واحد} =2{عنصران} few{{count} عناصر} many{{count} عنصرًا} other{{count} عنصر}}"

// Japanese: 1 form (other)
"itemCount": "{count, plural, other{{count}個のアイテム}}"

// German: 2 forms (=1, other)
"itemCount": "{count, plural, =1{1 Artikel} other{{count} Artikel}}"

// Russian: 3 forms (one, few, many)
"itemCount": "{count, plural, =0{Нет товаров} one{{count} товар} few{{count} товара} many{{count} товаров} other{{count} товаров}}"
Variables and named arguments
// Simple variable
"welcome": "Welcome, {name}!"

// Multiple variables
"orderStatus": "Order #{orderId} — {status}"

// Variable in plural context
"unreadMessages": "{count, plural, =0{No unread messages} =1{1 unread message from {sender}} other{{count} unread messages}}"

// In widgets:
Text('welcome'.tr(namedArgs: {'name': userName}));
Text('orderStatus'.tr(namedArgs: {'orderId': '1234', 'status': 'Shipped'}));
Text('unreadMessages'.plural(count, namedArgs: {'sender': senderName}));
if (count == 1) से एकवचन/बहुवचन का नियम कभी हार्डकोड न करें। फ़्रेंच जैसी भाषाएँ 0 को एकवचन मानती हैं। रूसी, पोलिश और अरबी में ऐसे बहुवचन रूप हैं जो अंग्रेज़ी में बिल्कुल नहीं होते। हमेशा ICU बहुवचन सिंटैक्स इस्तेमाल करें और फ़्रेमवर्क को सही रूप चुनने दें।
6

RTL भाषाओं का समर्थन करें

जब लोकेल दाएँ-से-बाएँ लिखी जाने वाली भाषा (अरबी, हिब्रू, फ़ारसी या उर्दू) का हो, तो Flutter पूरे लेआउट को अपने-आप मिरर करता है। लेकिन सही मिररिंग के लिए आपके कोड में दिशा को ध्यान में रखने वाले विजेट और प्रॉपर्टी इस्तेमाल होने चाहिए। हार्डकोड किए गए left/right की जगह start/end के समकक्ष मान इस्तेमाल करें।

lib/widgets/adaptive_layout.dart
import 'package:flutter/material.dart';

class AdaptiveLayout extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final isRtl = Directionality.of(context) == TextDirection.rtl;

    return Scaffold(
      body: Row(
        children: [
          // Use start/end instead of left/right
          Expanded(
            child: Padding(
              padding: EdgeInsetsDirectional.only(
                start: 16.0,  // Leading edge (left in LTR, right in RTL)
                end: 8.0,     // Trailing edge
              ),
              child: Text('content'.tr()),
            ),
          ),
          // Flip icons for RTL
          Icon(
            isRtl ? Icons.arrow_back : Icons.arrow_forward,
          ),
        ],
      ),
    );
  }
}
RTL-aware widget patterns
// Use Directional widgets for RTL-aware layouts
EdgeInsetsDirectional.only(start: 16, end: 8)   // Not EdgeInsets.only(left: 16, right: 8)
AlignmentDirectional.centerStart                  // Not Alignment.centerLeft
BorderRadiusDirectional.only(topStart: Radius.circular(8))

// Automatically mirrors when locale changes to Arabic, Hebrew, etc.
// No conditional logic needed — Flutter handles text direction from locale
अपने ऐप का locale अस्थायी रूप से Arabic (Locale('ar')) पर सेट करके RTL जाँचें। Flutter पूरे UI को mirror करता है—navigation drawers दाईं ओर से खुलते हैं, back arrows पलट जाते हैं और टेक्स्ट दाईं ओर align होता है। अपने custom layouts की सही mirroring सुनिश्चित करने के लिए EdgeInsetsDirectional, AlignmentDirectional और BorderRadiusDirectional इस्तेमाल करें।
7

स्मार्ट Locale Fallback चेन

डिफ़ॉल्ट रूप से pt-BR अनुवाद न मिलने पर Flutter उपयोगी pt-PT अनुवादों को छोड़कर सीधे English पर लौटता है। locale_chain पैकेज configurable fallback chains से इसे ठीक करता है। सेटअप की केवल एक लाइन और migration की कोई आवश्यकता नहीं—आपकी मौजूदा .tr() calls सीधे काम करती हैं।

lib/main.dart with LocaleChain
import 'package:locale_chain/locale_chain.dart';
import 'package:locale_chain/easy_localization.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await EasyLocalization.ensureInitialized();
  LocaleChain.configure();  // Enable smart fallback chains

  runApp(
    EasyLocalization(
      supportedLocales: [
        Locale('en'),
        Locale('pt', 'BR'),
        Locale('pt', 'PT'),
        Locale('es'),
        Locale('es', 'MX'),
      ],
      path: 'assets/translations',
      assetLoader: LocaleChainAssetLoader(  // Swap in the chain loader
        baseLoader: RootBundleAssetLoader(),
      ),
      fallbackLocale: Locale('en'),
      child: MyApp(),
    ),
  );
}

// Result: pt-BR user sees pt-PT translations when pt-BR keys are missing,
// instead of falling back directly to English.
Custom fallback configuration
// Override specific chains while keeping built-in defaults
LocaleChain.configure(
  fallbacks: {
    'pt-BR': ['pt-PT', 'pt'],      // pt-BR → pt-PT → pt → en
    'es-MX': ['es-419', 'es'],     // es-MX → es-419 → es → en
    'fr-CA': ['fr'],               // fr-CA → fr → en
  },
);

// Or replace all defaults with your own chains
LocaleChain.configure(
  fallbacks: {
    'zh-Hant-HK': ['zh-Hant-TW', 'zh-Hans'],
    'pt-BR': ['pt-PT', 'pt'],
  },
  mergeDefaults: false,  // Only your chains, no built-in defaults
);
locale_chain में Portuguese, Spanish, French, German, Italian, Dutch, Norwegian और Malay के regional variants के लिए built-in fallback chains शामिल हैं। pt-BR उपयोगकर्ता को English से पहले pt-PT content दिखाई देगा। es-MX उपयोगकर्ता को default locale से पहले es-419 और फिर es दिखाई देगा।
8

अनुवाद स्वचालित करें

स्थानीयकरण सेटअप पूरा होने के बाद AI से अपनी ARB फ़ाइलों का अनुवाद करें। अपने IDE में AI assistant से source ARB फ़ाइल का अनुवाद करने के लिए कहें या अपनी CI/CD pipeline में i18n Agent CLI इस्तेमाल करें। ARB metadata (placeholders, विवरण) ऐसा संदर्भ देता है जिससे अनुवाद की गुणवत्ता बेहतर होती है।

Terminal
# In your IDE, ask your AI assistant:
> Translate assets/translations/en.arb to Arabic, Japanese, and German

✓ ar.arb created (1.4s)
✓ ja.arb created (1.2s)
✓ de.arb created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate assets/translations/en.arb --lang ar,ja,de
अनुवाद चरणबद्ध रूप से करें—अपनी source ARB फ़ाइल में नई keys जोड़ने पर सभी फ़ाइलें दोबारा बनाने के बजाय केवल diff का अनुवाद करें। इससे मनुष्यों द्वारा जाँचे गए अनुवाद सुरक्षित रहते हैं और आपका ARB metadata ज्यों का त्यों बना रहता है।

अनुवाद की गुणवत्ता स्वचालित करें

i18n-validate से missing keys और टूटे हुए placeholders को रिलीज़ होने से पहले पकड़ें। वास्तविक अनुवाद आने से पहले i18n-pseudo की pseudo-translations से अपने UI की जाँच करें।

आम समस्याएँ

Runtime पर अनुवाद फ़ाइलें नहीं मिलीं

आपकी ARB/JSON फ़ाइलें pubspec.yaml के assets section में घोषित होनी चाहिए। यह चरण छूटने पर डिस्क पर मौजूद होने के बावजूद Flutter runtime पर फ़ाइलें नहीं खोज पाता। यह जोड़ें: assets: - assets/translations/

अमान्य ARB फ़ाइल Syntax

ARB फ़ाइलें strict JSON होती हैं—इनमें trailing commas, single quotes या comments की अनुमति नहीं है। एक syntax error भी पूरी फ़ाइल को बिना कोई सूचना दिए लोड होने से रोक देती है। अनुवाद संबंधी समस्याएँ debug करने से पहले JSON linter से अपनी ARB फ़ाइलें validate करें।

Hot Reload पर अनुवाद के बदलाव दिखाई नहीं दे रहे

easy_localization अनुवादों को memory में cache करता है। नई keys जोड़ने या मौजूदा अनुवाद बदलने के बाद बदलाव लागू करने के लिए full hot restart (hot reload नहीं) आवश्यक हो सकता है। डेवलपमेंट के दौरान अनुवाद फ़ाइलें edit करने के बाद hot restart (Shift+R) इस्तेमाल करें।

Hardcoded Left/Right से RTL का टूटना

EdgeInsetsDirectional.only(start: 16) की जगह EdgeInsets.only(left: 16) इस्तेमाल करने पर Flutter, RTL भाषाओं के लिए आपके लेआउट को mirror नहीं कर पाता। Directional suffix के बिना EdgeInsets, Alignment और BorderRadius खोजने के लिए अपना codebase search करें।

सुझाई गई फ़ाइल संरचना

Project Structure
my_flutter_app/
├── assets/
│   └── translations/
│       ├── en.arb          # Source language (English)
│       ├── ar.arb          # Arabic (with 6 plural forms)
│       ├── de.arb          # German
│       ├── ja.arb          # Japanese
│       ├── pt-BR.arb       # Brazilian Portuguese
│       └── pt-PT.arb       # European Portuguese
├── lib/
│   ├── main.dart           # App entry with EasyLocalization
│   ├── app.dart            # MaterialApp with locale delegates
│   └── widgets/
│       └── language_switcher.dart
├── pubspec.yaml            # Dependencies
└── analysis_options.yaml

i18n Agent अभी आज़माएँ

अपनी अनुवाद फ़ाइल यहाँ छोड़ें

JSON, YAML, PO, XML, CSV, Markdown, Properties

या ब्राउज़ करने के लिए क्लिक करें

लक्षित भाषाएँ

साइन अप की ज़रूरत नहींतुरंत अनुमान

locale_chain के साथ Locale Fallback

जब pt-BR जैसे regional locale में कोई translation key नहीं मिलती, तो Flutter पहले parent locale pt को जाँचने के बजाय सीधे template language पर पहुँच जाता है।

Terminal
flutter pub add locale_chain
Configuration
import 'package:locale_chain/locale_chain.dart';

LocaleChain.configure(fallbacks: {
  'pt-BR': ['pt', 'en'],
  'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
});

LocaleChainAssetLoader(baseLoader: RootBundleAssetLoader());

समर्थित frameworks और 75 built-in chains की पूरी सूची के लिए हमारी Locale Fallback गाइड देखें। Learn more →

अक्सर पूछे जाने वाले प्रश्न