VeryGoodOpenSource/r13n

🌐 r13n

Deprecated: This repository has been archived and is no longer maintained. The r13n package has been discontinued on pub.dev and the r13n brick has been discontinued on BrickHub. There will be no further updates, bug fixes, or official support from Very Good Ventures.

If you need to continue development, you are welcome to fork this repository.

Very Good Ventures Very Good Ventures

ci coverage style: very good analysis License: MIT Powered by Mason

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 🚀

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

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

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"
}

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

$ dart pub global activate mason_cli

Then, install the r13n brick globally.

$ mason add r13n -g

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

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

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(...)
      ...
    );

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 🗺

Note: This roadmap will not be pursued. The package is discontinued and this repository is archived.

[ ] 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.

VeryGoodOpenSource/r13n