README.md

🌐 r13n

---

A Flutter package that makes regionalization easy. Heavily inspired by flutter_localizations and intl.

Similar to l10n which is short for localization, this package is called r13n as shorthand for regionalization.

Developed with 💙 by Very Good Ventures 🦄

What is regionalization? 📍

Regionalization helps you display text in the app based on a person's region.

Example: Say your app’s users are in the US and the UK. On your support page, you want to display the correct support email based on the user’s region. You can use the r13n package to display support.uk@mycompany.com to users in the UK and support.us@mycompany.com to users in the US.

Similarly, l10n helps you display translations based on the user’s locale.

Example: When using l10n, your app will display text in the user’s preferred language.

The r13n package can and should be used in conjunction with l10n. r13n is an additional mechanism to personalize information presented to users in an app.

How it works ⚙️

Similar to l10n, the r13n package uses .arb files to house the region-specific configurations.

The arb file contains strings for region-specific values. The r13n brick is used to generate compile-safe Dart code in order to access the correct versions of each value based on the user's region.

Quick Start 🚀

1. For each supported region, add a new .arb file in lib/r13n/arb.

├── r13n
│   ├── arb
│   │   ├── app_gb.arb
│   │   └── app_us.arb

2. Add the translated strings to each .arb file:

app_us.arb

{
    "@@region": "us",
    "supportEmail": "us@verygood.ventures"
}

app_gb.arb

{
    "@@region": "gb",
    "supportEmail": "gb@verygood.ventures"
}

3. If you don't already have mason_cli, use the following command:

$ dart pub global activate mason_cli

4. Then, install the r13n brick globally.

$ mason add r13n -g

5. Add a new yaml file to the root directory of the Flutter project called r13n.yaml with the following content:

arb-dir: lib/r13n/arb
template-arb-file: app_us.arb

6. Generate files.

$ mason make r13n --on-conflict overwrite

├── r13n
│   ├── arb
│   │   ├── gen
│   │   │   ├── app_regionalizations_gb.g.dart
│   │   │   ├── app_regionalizations_us.g.dart
│   │   │   └── app_regionalizations.g.dart
│   │   ├── app_us.arb
│   │   └── app_gb.arb

7. Add a Regionalizations widget to the widget tree.

class MyApp extends StatelessWidget {

  @override
  Widget build(BuildContext context) {
    return Regionalizations(
      region: Region.fromPlatform(),
      delegates: const [AppRegionalizations.delegate],
      child: MaterialApp(...)
      ...
    );

8. Use the new string.

import 'package:example/r13n/r13n.dart';

@override
Widget build(BuildContext context) {
  final r13n = AppRegionalizations.of(context);
  return Text(r13n.supportEmail);
}

Roadmap 🗺

• Support asynchronous delegates
• Support regionalization based on IP address
• Provide API's to support sub-regions (for example, states in the U.S.)

Additional Resources 📚

For more information, see the example, the r13n brick and the source code.