{"id":22353036,"url":"https://github.com/esskar/vscode-flutter-i18n-json","last_synced_at":"2025-07-30T08:33:52.924Z","repository":{"id":36247928,"uuid":"175700568","full_name":"esskar/vscode-flutter-i18n-json","owner":"esskar","description":"VS Code extension to create a binding between your translations from .json files and your Flutter app.","archived":false,"fork":false,"pushed_at":"2022-08-08T19:32:53.000Z","size":3956,"stargazers_count":93,"open_issues_count":24,"forks_count":21,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2024-05-01T23:53:08.806Z","etag":null,"topics":["flutter","i18n","vscode","vscode-extension"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esskar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-14T21:13:36.000Z","updated_at":"2023-10-16T01:13:42.000Z","dependencies_parsed_at":"2022-07-15T20:17:12.780Z","dependency_job_id":null,"html_url":"https://github.com/esskar/vscode-flutter-i18n-json","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esskar%2Fvscode-flutter-i18n-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esskar%2Fvscode-flutter-i18n-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esskar%2Fvscode-flutter-i18n-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esskar%2Fvscode-flutter-i18n-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esskar","download_url":"https://codeload.github.com/esskar/vscode-flutter-i18n-json/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228110852,"owners_count":17871248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flutter","i18n","vscode","vscode-extension"],"created_at":"2024-12-04T12:32:36.144Z","updated_at":"2024-12-04T12:33:28.137Z","avatar_url":"https://github.com/esskar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vscode-flutter-i18n-json\n\nVS Code extension to create a binding between your translations from .json files and your Flutter app. You can also automagically generate translations for all your locales, based on Google Translate.\n\n## Installation\n\nTo install the extension just execute the following command:\n\n    ext install vscode-flutter-i18n-json\n\nYou may also install the extension from the [visual studio code marketplace][1].\n\n## Getting started\n\n1. Install the extension\n2. Open your project, open the command palette and find the `Flutter I18n Json: Initialize` command.\n3. Enter a default locale, or press enter to use `en-US`.\n\n![init-command](https://raw.githubusercontent.com/esskar/vscode-flutter-i18n-json/master/images/extension_init.gif)\n\n## Commands\n\n### Flutter I18n Json: Initialize\n\nCreates the inital binding between translations from .json files and your Flutter app.\nThe command will ask you for the default locale, the locale that will be used when no other locale can be matched.\n\nThe following files will be created:\n\n    i18n/\u003cdefault-locale\u003e.json\n    lib/generated/i18n.dart\n    i18nconfig.json\n\n### Flutter I18n Json: Add locale\n\nAdds another locale to your Flutter app.\nThe command will ask you for a new locale.\n\nThe following files will be created:\n\n    i18n/\u003cnew-locale\u003e.json\n\nand updated:\n\n    lib/generated/i18n.dart\n    i18nconfig.json\n\n### Flutter I18n Json: Update\n\nAfter you change or add any translations, run the update command to update\n\n    lib/generated/i18n.dart\n\nto reflect your translation changes.\n\n### Flutter I18n Json: Remove locale\n\nRemoves an existing locale from your Flutter app.\nThe command will ask you to pick a locale from the list of existing locales.\n\nThe following files will be removed:\n\n    i18n/\u003cexisting-locale\u003e.json\n\nand updated:\n\n    lib/generated/i18n.dart\n    i18nconfig.json\n\n### Flutter I18n Json: Set Google Translate API Code\n\nSets the API code for the Google Translate API.\n\nTo obtain an API key, you need to have an account with the Google Cloud Platform:\n\n* Go to: https://console.developers.google.com/apis/dashboard\n* Select (or create) a project\n* Click button \"Enable API's and services\" (on top)\n* Search for \"Cloud Translation API\"\n* Click \"Enable\"\n* Once enabled, go to the \"Credentials\" (left side) section on your API overview\n* Click \"Create credential\" (top bar)\n* In de text \"We'll help you set up the correct credentials. \nIf you want you can skip this step and create an API key, client ID or service account.\", **choose the link \"API key\"**.\n* Give it a name and click \"Create\"\n\nYou can copy the key now.\n\nThe following file will be updated:\n\n    i18nconfig.json\n\n### Flutter I18n Json: Create automagic translations from default locale\n\nGenerates and adds missing translations to `i18n/\u003clocale\u003e.json` files, based on the translation keys and values in `i18n/\u003cdefault-locale\u003e.json`.\n\nWhen using this command, you don't have to manually add every translation key and translated value to all `i18n/\u003clocale\u003e.json` files.\n\n## Usage\n\n### JSON\n\nUse a simple key-value pair JSON format to define your translations.\n\n```json\n{\n    \"hello\": \"Hello\"\n}\n```\n\nIn the above example `\"hello\"` is the key for the translation value `\"Hello!\"`. \n\nPlaceholders are automatically detected and are enclosed in curly brackets (`{}`):\n\n```json\n{\n    \"greetTo\": \"Hello {name}\"\n}\n```\n\nHere, `{name}` is a placeholder within the translation value for `\"greetTo\"`.\n\n### Dart\n\nLet's add some translations in `i18n/en-US.json`:\n\n```json\n{\n    \"hello\": \"Hello!\",\n    \"greetTo\": \"Nice to meet you, {name}!\"\n}\n```\n\nAfter you run the update command, you will see that in `lib/generated/i18n.dart`, a getter `hello` and a method `greetTo` were created:\n\n```dart\nclass I18n implements WidgetsLocalizations {\n  const I18n();\n\n  static const GeneratedLocalizationsDelegate delegate = \n    const GeneratedLocalizationsDelegate();\n\n  static I18n of(BuildContext context) =\u003e\n    Localizations.of\u003cI18n\u003e(context, WidgetsLocalizations);\n\n  @override\n  TextDirection get textDirection =\u003e TextDirection.ltr;\n\n  String get hello =\u003e \"Hello!\";\n  String greetTo(String name) =\u003e \"Nice to meet you, ${name}!\";\n}\n```\n\nUsing the generated `I18n` class is showcased in the example below:\n\n```dart\n@override\nWidget build(BuildContext context) {\n  final i18n = I18n.delegate;\n  return new MaterialApp(\n    localizationsDelegates: [\n      i18n\n    ],\n    supportedLocales: i18n.supportedLocales,\n    localeResolutionCallback: i18n.resolution(fallback: new Locale(\"en\", \"US\"))\n    // .. any other properties supported and required by your application\n  );\n```\n\nWhen translating something, simply call your translation like this:\n\n```dart\nI18n.of(context).hello\n```\n_This returns a string you can direcly use in e.g. a Text() widget_\n\n### Nesting\n\nNesting is supported which allows you to hierarchically structure the translations.\n\n```json\n{\n    \"hello\": \"hello!\",\n    \"greeting\": {\n        \"formal\": \"Hello\",\n        \"informal\": \"Hi\",\n        \"placeholder\": {\n            \"formal\": \"Hello {name}\",\n            \"informal\": \"Hi {name}\"\n        }\n    }\n}\n```\n\nThe above file will generate the following dart code\n\n```dart\n/// \"hello!\"\nString get hello =\u003e \"hello!\";\n/// \"Hello\"\nString get greetingFormal =\u003e \"Hello\";\n/// \"Hi\"\nString get greetingInformal =\u003e \"Hi\";\n/// \"Hello ${name}\"\nString greetingPlaceholderFormal(String name) =\u003e \"Hello ${name}\";\n/// \"Hi ${name}\"\nString greetingPlaceholderInformal(String name) =\u003e \"Hi ${name}\";\n````\n\n### Arrays\n\nArrays of strings is supported too.\n\n```json\n{\n    \"hello\": \"hello!\",\n    \"greetings\": [\n        \"Hello\",\n        \"Hi\"\n    ]\n}\n```\n\nThe above file will generate the following dart code\n\n```dart\n/// \"hello!\"\nString get hello =\u003e \"hello!\";\n/// [\"Hello\", \"Hi\"]\nList\u003cString\u003e get greetings =\u003e [\"Hello\", \"Hi\"];\n````\n\n### Changing locale manually\n\nLocale can be changed manually using static `locale` parameter. To make application reload from anywhere in the app you can use static `onLocaleChanged` callback:\n\n```dart\nimport 'package:flutter_localizations/flutter_localizations.dart';\n\nclass MyApp extends StatefulWidget {\n  @override\n  _MyAppState createState() =\u003e _MyAppState();\n}\n\nclass _MyAppState extends State\u003cMyApp\u003e {\n  final i18n = I18n.delegate;\n\n  @override\n  void initState() {\n    super.initState();\n    I18n.onLocaleChanged = onLocaleChange;\n  }\n\n  void onLocaleChange(Locale locale) {\n    setState(() {\n      I18n.locale = locale;\n    });\n  }\n\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      title: app,\n      localizationsDelegates: [\n        i18n,\n        GlobalMaterialLocalizations.delegate,\n        GlobalWidgetsLocalizations.delegate,\n        GlobalCupertinoLocalizations.delegate // \u003c-- needed for iOS\n      ],\n      supportedLocales: i18n.supportedLocales,\n     home: \u003cyour home widget\u003e\n    );\n  }\n}\n```\n\nCalling this anywhere in your app will now change the app's language\n\n```dart\nI18n.onLocaleChanged(newLocale);\n```\n\n\n\n### Generate translations\n\nAfter you run the Create automagic translations-command, all translation files will be supplemented with the new translations.\n\nFor instance, if you added the `greetTo` key from above, with this command your `i18n/es-ES.json` goes from\n\n```json\n{\n    \"hello\": \"¡Hola!\"\n}\n```\nto\n\n```json\n{\n    \"hello\": \"¡Hola!\",\n    \"greetTo\": \"Encantado de conocerte, {name}!\"\n}\n```\n\n\n\nThe **run the update command** will run automatically after any successful automagic translation, so you'll see that the Spanish WidgetsLocalizations are updated as:\n\n```dart\nclass _I18n_es_ES extends I18n {\n  const _I18n_es_ES();\n\n  @override\n  String get hello =\u003e \"¡Hola!\";\n  @override\n  String greetTo(String name) =\u003e \"Encantado de conocerte, ${name}!\";\n}\n```\n## Text direction\n\nStarting form version 0.12.0 the module detects the text direction automatically - based on the language code.\nIf you want to change the automatic behaviour, you can change the text direction in the `i18nconfig.json` file:\n\n    {\n      rtl: [\"ar-AR\"],\n      ltr: []\n    }\n\n\n## Troubleshooting\n\n### iOS\n\nBy default, your languages are not supported by iOS out of the box. To enable them, add the following to your `your_project/ios/Runner/Info.plist` file:\n\n```xml\n\u003ckey\u003eCFBundleLocalizations\u003c/key\u003e\n  \u003carray\u003e\n    \u003cstring\u003een\u003c/string\u003e\n    \u003cstring\u003ees\u003c/string\u003e\n    \u003cstring\u003eru\u003c/string\u003e\n  \u003c/array\u003e\n```\n_(with `en`, `es` and `ru` being examples for English, Spanish and Russian)_\n\nYour file should look something like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n  \u003ckey\u003eCFBundleDevelopmentRegion\u003c/key\u003e\n  \u003cstring\u003een\u003c/string\u003e\n  \u003ckey\u003eCFBundleExecutable\u003c/key\u003e\n  \u003cstring\u003e$(EXECUTABLE_NAME)\u003c/string\u003e\n  \u003ckey\u003eCFBundleLocalizations\u003c/key\u003e\n  \u003carray\u003e\n    \u003cstring\u003een\u003c/string\u003e\n    \u003cstring\u003ees\u003c/string\u003e\n    \u003cstring\u003eru\u003c/string\u003e\n  \u003c/array\u003e\n  \u003ckey\u003eCFBundleIdentifier\u003c/key\u003e\n  \u003cstring\u003e$(PRODUCT_BUNDLE_IDENTIFIER)\u003c/string\u003e\n  \u003ckey\u003eCFBundleInfoDictionaryVersion\u003c/key\u003e\n  \u003cstring\u003e6.0\u003c/string\u003e\n.\n.\n.\netc...\n```\n\n\n[1]: https://marketplace.visualstudio.com/items?itemName=esskar.vscode-flutter-i18n-json\nThere are still some [unresolved issues][2] in Flutter when trying to use localization with the iOS simulators. For more information to address this issue check the [flutter documentation][3]. \n\n### No Material-/CupertinoLocalizations found.\n\nGlobal widgets may throw exceptions informaing you that they cannot find any MaterialLocalizations (`No MaterialLocalizations found.`). You need to install them manually and add their delegates to your localizationsDelegates.\n\nin your pubspec.yaml:\n\n    dev_dependencies:\n      flutter_localizations:\n        sdk: flutter\n\nin your app:\n\n```dart\nimport 'package:flutter_localizations/flutter_localizations.dart';\n\nreturn new MaterialApp(\n    localizationsDelegates: [\n      i18n,\n      GlobalMaterialLocalizations.delegate,\n      GlobalWidgetsLocalizations.delegate,\n      GlobalCupertinoLocalizations.delegate\n      ...\n```\n\n[1]: https://marketplace.visualstudio.com/items?itemName=esskar.vscode-flutter-i18n-json\n[2]: https://github.com/flutter/flutter/issues/14128\n[3]: https://flutter.dev/docs/development/accessibility-and-localization/internationalization#appendix-updating-the-ios-app-bundle\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesskar%2Fvscode-flutter-i18n-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesskar%2Fvscode-flutter-i18n-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesskar%2Fvscode-flutter-i18n-json/lists"}