localize_it

Welcome to localize_it, yet another package for localizing your app.

Motivation

This package is dedicated to everyone who had to localize a whole app from scratch. Flutter is awesome, but localizing your app can cause serious pain and demotivation.

We may have to:

configure your localization for each project from scratch
think of a key for each String we want to localize
access context everywhere we want to localize
hire a Translation Service Provider for proper translation
...

Implementing all of this can take extra hours or days of extra work, which can be frustrating because it is also rather simple work but a lot.

Localize_it tries to fix that by doing all the annoying work for you, allowing you to focus on developing your app and make it globally available.

Before	After
`AppLocalizations.of(context).thisIsAnAnnoyingText`	`This is so easy`.tr

How to use

1. Install

To use localize_it, you will need your typical build_runner/code-generator setup.
First, install build_runner and localize_it by adding them to your pubspec.yaml file:

For a Flutter project:

flutter pub add localize_it_annotation
flutter pub add --dev build_runner
flutter pub add --dev localize_it

For a Dart project:

dart pub add localize_it_annotation
dart pub add --dev build_runner
dart pub add --dev localize_it

This installs three packages:

build_runner, the tool to run code-generators
localize_it, the code generator
localize_it_annotation, a package containing annotations for localize_it.

2. localize_it x GetX

To get the most out of this package make sure to install GetX as well. With that you can simply call .tr behind every String you want to translate.

This also gives you access to multiple other utils. See more on GetX.

3. Setup Config file (with VSCode Extension)

Next Step is to setup a config-file. Writing code by yourself? Haha.

Lucky for you there is a VSCode-Extension.

After installling it you can simply call localize_it: Create anywhere inside your lib/. Easy!

4. Configure

Field	Description
`baseLanguageCode`	`String` that expects a lanugage code in lowercase.
	Supports all the currently available Source Languages (`source_lang`)
	on DeepL.

	Defaults to: `'de' (German)`
`supportedLanguageCodes`	`List<String` that expects lanugage codes in lowercase.
	Should not contain `baseLanguageCode`
	Supports all the currently available Target Languages (`target_lang`)
	on DeepL.

	Defaults to: `['en' (English), 'es' (Spanish)]`
`deepLAuthKey`	`String` that expects your DeepL Auth Key
	Providing a `deepLAuthKey` enables translation generation
	via the DeepL API.
	If no key is provided (empty String), all marked Strings (end with `.tr`)

	in your project will get translated to `'--missing translation--'`.
`useGetX`	If `true` a file called `translation_keys.dart` is created that
	maps `supportedLanguageCodes` to their localization-files.
	`translation_keys` can simply be passed to `GetMaterialApp`

	to enable Localization.
`preferDoubleQuotes`	By default localize_it is searching for `Strings` in singel-quotes.
	See prefer_single_quotes for more info.
	However if you prefer using double quotes in your project you can do this
	by setting `preferDoubleQuotes` to `true`.

5. Disable generate

For the build_runner to work you must disable generate in your pubspec.yaml:

flutter:
  # generate: true

See more on this issue.

6. Localize!

You're ready to go!

Clean!

Make sure to clean your project before calling the build_runner:

flutter clean
flutter pub get

Let build_runner do the rest for you:

flutter pub run build_runner build --delete-conflicting-outputs

This will find all Strings that end with .tr in your project and localize them depending on your baseLanugageCode and supportedLanguageCodes.

Good to know

You can always change the translated text in your localization filels. The change/adjust will NOT be overritten when calling the script again.
You can call the script as often you want. Only the newly added Strings will be translated. This increases performance and makes sure that you don't reach your DeepL API limit.
Strings that you removed from your projects but are still in your localizations will be removed once you call the script again.

Enjoy!

Open Issues

Add Support to differenciate American/British English
Having a ",\n" inside a String that should get localized will break the generator
Get deepLAuthKey from .env