This is the second part of the blog post series that aims to implement the February Challenge of flutterchallenge.dev the Tinder for Cats and Dogs.

This post shows an implementation of the communication layer of our application by using the chopper package.

You can find the source code at https://github.com/dtengeri/tinder_cat_dog_app

What is chopper?

What does the chopper package provide us and why it is useful?

chopper is an HTTP client generator. It generates source code for you, to manage HTTP calls in your app. It generates the boring stuff, you just need to define the methods and annotate them with some meta information, chopper will translate it to HTTP calls and handles JSON serialization, HTTP headers and every HTTP related configuration for you.

Add chopper to your app

Let's add chopper to the Tinder for Cats and Dogs application.

Just for a remainder, the Tinder for Cats and Dogs was the first challenge of flutterchallenge.dev. It provides a REST API to get the list of available cats and dogs and to store the user's votes.

Let's start with adding the required dependencies to our application.

dependencies:
  chopper: ^4.0.5

dev_dependencies:
  build_runner: ^2.1.11
  chopper_generator: ^4.0.5

Since chopper is a code generator, we are going to use the build_runner to generate the code the same way as for freezed in the first part of the series.

Chopper basics

chopper main class is the ChopperClient which does the communication with our backend service. It relies on services. A service is a ChopperService, which is the generated code for the endpoints. Since we are using freezed it provides us JSON serialization as well. We can create a custom converter for chopper so it can automatically convert the request and response body from JSON to our models.

Create the first service

Let's start with creating our first service, for the /cats endpoint.

import 'package:chopper/chopper.dart';
import 'package:tinder_cat_dog_app/features/animals/animals.dart';

// The place of the generated code.
part 'cat_list_service.chopper.dart';

// This annotation tells chopper that this service
// should send its requests to the /cats path.
@ChopperApi(baseUrl: '/cats')
abstract class CatListService extends ChopperService {
  // This method creates the service based on the generated code.
  static CatListService create([ChopperClient? client]) =>
      _$CatListService(client);

  // This tells chopper to generate a method that wil send a GET request
  // to the /cats endpoint and returns a list of Cat models.
  @Get()
  Future<Response<List<Cat>>> getCats();
}

chopper provides annotations that can be used to aid the code generation. In the CatListService we define a getCats() method that will send a GET request to our REST API's /cats endpoint. The endpoint's response is in JSON format

[
  {
    "id": "9eef0518d8b5a333ee1fcb1a06a1474a23192c6a",
    "name": "Luna",
    "path": "/cats/cat001.jpeg"
  }
]

The generated code processes this JSON string and converts its content to our Cat model and adds all cats to a list. And all of this happens by just adding the @Get() annotation.

Run

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

to generate the service or watch your file changes and generate the chopper services automatically by

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

Processing JSON strings

We can provide converters to ChopperClient that could process JSON strings and convert them to our own models.

import 'package:chopper/chopper.dart';
import 'package:tinder_cat_dog_app/features/core/core.dart';

/// This function gets a JSON map and returns a model of type [T].
typedef JsonFactory<T> = T Function(Map<String, dynamic> json);

/// A [JsonConverter] for chopper that uses converts our models to and 
/// from JSON.
class JsonSerializableConverter extends JsonConverter {
  /// Creates a new [JsonSerializableConverter] with the given [factories].
  const JsonSerializableConverter(this.factories);
  /// Collection of the factories of our model [Type]s. 
  final Map<Type, JsonFactory> factories;

  T _decodeMap<T>(Map<String, dynamic> values) {
    /// Get jsonFactory using Type parameters
    /// if not found or invalid, throw error or return null
    final jsonFactory = factories[T];
    if (jsonFactory == null || jsonFactory is! JsonFactory<T>) {
      /// throw serializer not found error;
      throw ArgumentError('Serializer not found');
    }

    return jsonFactory(values);
  }

  List<T> _decodeList<T>(List values) =>
      values.where((v) => v != null).map<T>((v) => _decode<T>(v)).toList();

  dynamic _decode<T>(entity) {
    if (entity is Iterable) return _decodeList<T>(entity.toList());

    if (entity is Map<String, dynamic>) return _decodeMap<T>(entity);

    return entity;
  }

  /// Converts a reponse coming from the server to [ResultType].
  @override
  Response<ResultType> convertResponse<ResultType, Item>(Response response) {
    final jsonRes = super.convertResponse(response);

    return jsonRes.copyWith<ResultType>(body: _decode<Item>(jsonRes.body));
  }

  /// Converts the request body if it implements [ToJsonConvertable].
  /// 
  /// It calls [ToJsonConvertable.toJson] method on the body to convert
  /// the body to JSON string.
  @override
  Request convertRequest(Request request) {
    final convertedRequest = super.convertRequest(request);
    if (request.body is ToJsonConvertable) {
      return convertedRequest.copyWith(
        body: (request.body as ToJsonConvertable).toJson(),
      );
    }
    return convertedRequest;
  }

  @override
  Response convertError<ResultType, Item>(Response response) {
    final jsonRes = super.convertError(response);

    return jsonRes;
  }
}

There are 2 key parts in the converter.

1. We have to provide a map for all the types that our chopper client can handle through the REST APIs. This map contains the factory functions that could convert a JSON map to the given type. Such a function is Cat.fromJson, which is generated by freezed.
2. In the convertRequest method we are checking the type of the request body. If it implements ToJsonConvertable and has a toJson() method, it will use it to convert the data class to JSON. This is true for our models generated by freezed. We only have to extend or implement the ToJsonConvertable class.

import 'package:freezed_annotation/freezed_annotation.dart';
import 'package:tinder_cat_dog_app/features/core/core.dart';

part 'vote_param.freezed.dart';
part 'vote_param.g.dart';

/// Extend [ToJsonConvertable] so [VoteParam] can be used
/// as a request body and it will be converted automatically to JSON.
@freezed
class VoteParam extends ToJsonConvertable with _$VoteParam {
  const factory VoteParam({
    @JsonKey(name: 'vote_type') required String voteType,
    @JsonKey(name: 'animal_id') required String animalId,
    required bool liked,
  }) = _VoteParam;

  factory VoteParam.fromJson(Map<String, dynamic> json) =>
      _$VoteParamFromJson(json);
}

The ToJsonConvertable is an abstract class with the definition of toJson().

abstract class ToJsonConvertable {
  Map<String, dynamic> toJson();
}

Configure the requests

Let's see a more complex service that uses variables in the URLs, sends data as the request body and uses Authorization headers.

import 'package:chopper/chopper.dart';
import 'package:tinder_cat_dog_app/features/animals/animals.dart';

part 'vote_service.chopper.dart';

@ChopperApi(baseUrl: '/votes')
abstract class VoteService extends ChopperService {
  static VoteService create([ChopperClient? client]) => _$VoteService(client);

  // We can provide values for HTTP headers like authorization token
  // with the @Header annotation.
  @Get()
  Future<Response<List<Vote>>> getVotes({
    @Header('Authorization') required String token,
  });

  // We can use variables in the URL by using {variable-name} in the
  // @Get() annotation and marking a method parameter with @Path().
  @Get(path: '/{id}')
  Future<Response<Vote>> getVote({
    @Path() required String id,
    @Header('Authorization') required String token,
  });

  // We can provide the body of a POST request by annotate a method parameter
  // with @Body().
  @Post()
  Future<Response<Vote>> createVote({
    @Body() required VoteParam voteParam,
    @Header('Authorization') required String token,
  });

  @Put(path: '/{id}')
  Future<Response<Vote>> updateVote({
    @Path() required String id,
    @Body() required VoteParam voteParam,
    @Header('Authorization') required String token,
  });

  @Delete(path: '/{id}')
  Future<Response> deleteVote({
    @Path() required String id,
    @Header('Authorization') required String token,
  });
}

We can use variables in the URL, which will be replaced by one of the method parameters.

@Get(path: '/{id}')
  Future<Response<Vote>> getVote({
    @Path() required String id,
    @Header('Authorization') required String token,
  });

The {id} in the path creates a placeholder in the URL and the @Path() annotation before the id method parameter connects it to this placeholder.

We can provide HTTP headers as well by using @Header(). We can use it for example to set a JWT token in the Authorization header.

Create the ChopperClient

Let's configure the ChopperClient with our generated services and converter, so we can use it in our app. We're going to use a factory called ChopperClientFactory.

import 'package:chopper/chopper.dart';
import 'package:http/http.dart';
import 'package:tinder_cat_dog_app/features/animals/animals.dart';
import 'package:tinder_cat_dog_app/features/core/core.dart';

class ChopperClientFactory {
  /// Creates a new [ChopperClient] with our services and converter.
  static ChopperClient create([Client? client]) => ChopperClient(
        client: client,
        baseUrl: 'https://tinder-cat-dog-api.herokuapp.com',
        services: [
          // These are the services that we made and chopper
          // generated their logic.
          AuthService.create(),
          CatListService.create(),
          DogListService.create(),
          VoteService.create(),
        ],
        // This is our custom converter.
        converter: const JsonSerializableConverter({
          Cat: Cat.fromJson,
          Dog: Dog.fromJson,
          Vote: Vote.fromJson,
        }),
      );
}

Use our client

It's time to use our client to make HTTP requests. Let's create a new instance of it

final chopper = ChopperClientFactory.create();

Get the list of cats

final catListService = chopper.getService<CatListService>();
final response = await catListService.getCats();
if (response.statusCode == 200 && response.body != null) {
  for (Cat cat in response.body!) {
    // Do something with the cat.
  }
}

Create a vote

final voteService = chopper.getService<VoteService>();
final response = await voteService.createVote(
  token: 'Bearer xxxx',
  voteParam: const VoteParam(voteType: 'cat', animalId: '1', liked: true),
);

Summary

In this post, we created the communication layer of our application that uses the REST API and our data classes. The chopper package provides code generation features that help us quickly create services that communicate with our API. It generates the code for making HTTP requests. Our task is to annotate our methods and parameters and the rest is done by chopper.

Resources

You can find the source code of the application at https://github.com/dtengeri/tinder_cat_dog_app

freezed is a code generator tool that helps you build your data classes with tons of helpful features, like the copyWith() or fromJson() methods.

Add the dependencies

So let's start with a fresh new Flutter project and add freezed to the dependencies:

# pubspec.yaml
dependencies:
  freezed_annotation: ^1.1.0
  json_annotation: ^4.4.0

dev_dependencies:
  build_runner: ^2.1.8
  freezed: ^1.1.1
  json_serializable: ^6.1.5

The freezed_annotations will help us mark our classes so the freezed package will know which classes need to be generated when we run build_runner. If we add json_annotation and json_serializable to the dependencies as well, freezed can generate the toJson() and fromJson() methods as well.

Create our data representation

Let's see what we the REST API provides us. The challenge provides a swagger documentation about the available endpoints. Our goal is to have a class for each endpoint to represent its JSON response in our app.

Model the API with freezed

Let's start with the /cats endpoint which will return an array of cats in the following format

[
  {
    "id": "9eef0518d8b5a333ee1fcb1a06a1474a23192c6a",
    "name": "Luna",
    "path": "/cats/cat001.jpeg"
  }
]

So our Cat class should have 3 fields. This is how it could be created with the help of freezed. Let's create a cat.dart file under the folder lib/features/animals/models.

import 'package:freezed_annotation/freezed_annotation.dart';

// This file contains the generated code by freezed.
part 'cat.freezed.dart';
// This file contains the generated code by json_serializable.
part 'cat.g.dart';

// We mark the class with @freezed annotation so freezed knows it has 
// some to work to do.
// _$Cat is a generated class which contains all the constructors, 
// methods that makes our class immutable.
@freezed
class Cat with _$Cat {
  // With the help of this factory constructor we define the fields 
  // of our class.
  // _Cat is a class that will hold the implementation details. 
  const factory Cat({
    required String id,
    required String? name,
    required String path,
  }) = _Cat;
  // Adding this factory will instruct freezed and json_serializable to 
  // generate the fromJson() and toJson() methods for us.
  factory Cat.fromJson(Map<String, dynamic> json) => _$CatFromJson(json);
}

Now we have to run build_runner to generate the code so the cat.freezed.dart and cat.g.dart files are created and all the errors are eliminated from our IDE.

You can generate the code once by running

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

But if you are developing an app you can watch for changes and always generate the code without running manually the build_runner.

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

build_runner will scan your codebase and if there is a code generator that finds something to work on, it will execute it.

Let's move on to the next model, to the Vote. The /votes, and /votes/{id} endpoints. Whenever we get, create or modify a vote, the API responses with a structure like this.

{
  "id": 1,
  "user_id": 1,
  "vote_type": "cat",
  "animal_id": "9eef0518d8b5a333ee1fcb1a06a1474a23192c6a",
  "liked": true,
  "created_at": "2022-01-07T11:39:40.992Z",
  "updated_at": "2022-01-07T11:39:40.992Z"
}

We can do the same as we did with the cats.

import 'package:freezed_annotation/freezed_annotation.dart';

part 'vote.freezed.dart';
part 'vote.g.dart';

@freezed
class Vote with _$Vote {
  const factory Vote({
    required int id,
    required int user_id,
    required String vote_type,
    required String animal_id,
    required bool liked,
    required DateTime created_at,
    required DateTime updated_at,
  }) = _Vote;

  factory Vote.fromJson(Map<String, dynamic> json) => _$VoteFromJson(json);
}

In addition to the basic int and String types, the json_serialiable can handle DateTime as well. We have the part definitions, the class with the mixin and the factory method with the fields we want in our class along with the fromJson.

Represent the HTTP request body

When we want to create or modify a vote, the POST /votes and PUT /votes/{id} endpoints have a request body, which is basically a JSON with specific fields. We can represent this JSON the same way as we did with the data we are getting back from the API. So this

{
  "vote_type": "cat",
  "animal_id": "9eef0518d8b5a333ee1fcb1a06a1474a23192c6a",
  "liked": true
}

can be managed by

import 'package:freezed_annotation/freezed_annotation.dart';

part 'vote_param.freezed.dart';
part 'vote_param.g.dart';

@freezed
class VoteParam with _$VoteParam {
  const factory VoteParam({
    required String vote_type,
    required String animal_id,
    required bool liked,
  }) = _VoteParam;

  factory VoteParam.fromJson(Map<String, dynamic> json) =>
      _$VoteParamFromJson(json);
}

Following the above, we can represent our data in our app easily. If you don't want to do this manually and you are using VSCode, I can recommend the Json to Dart Model extension, which can generate your data classes from a JSON string and it can work with freezed.

Fix the linting errors

You'll get lint errors for the Vote class because of the variable naming

Name non-constant identifiers using lowerCamelCase.

You can fix this by using the JsonKey annotation like this

// ignore_for_file: invalid_annotation_target

import 'package:freezed_annotation/freezed_annotation.dart';

part 'vote_param.freezed.dart';
part 'vote_param.g.dart';

@freezed
class VoteParam with _$VoteParam {
  const factory VoteParam({
    @JsonKey(name: 'vote_type') required String voteType,
    @JsonKey(name: 'animal_id') required String animalId,
    required bool liked,
  }) = _VoteParam;

  factory VoteParam.fromJson(Map<String, dynamic> json) =>
      _$VoteParamFromJson(json);
}

By default, you'll get another lin error due to this issue, you can safely ignore it by putting the following at the top of your file.

// ignore_for_file: invalid_annotation_target

Summary

By using code generation, you can quickly add the data classes to your project to model a REST API. The good thing is that you'll get lots of features by default that can improve the quality of your projects in the long run and it can speed up your development time since you don't have to write the code by yourself.

You can find the relevant source code here.

In the next part of the series, I'll introduce the communication with the REST API with the help of the chopper package.

When you are working on a package that you want to share with others, either on pub.dev or internally with your team, you should provide documentation for your public API.

Luckily, we have a great example, the Flutter framework has really great documentation with lots of examples, code snippets.

We can make our package just as nice as the Flutter framework by writing our documentation as doc comments.

In order to write such a comment, we should start the comment with ///.

/// This class is an example of what we could achieve with 
/// dart doc comments
class MyAwesomeFeature {
  /// Creates a new instance of [MyAwesomeFeature] that can do
  /// some cool stuff on [title] and [subTitle].
  /// Usage: 
  /// ```dart
  /// MyAwesomeFeautre(
  ///   title: 'Hello',
  ///   subTitle: 'Flutter!',
  /// ).doSomeCoolThings();
  /// ```
  MyAwesomeFeature({
    required this.title,
    this.subTitle,
  });

  /// This will be the title of our feature.
  final String title;

  /// Optional subtitle, to better express ourselves.
  final String? subTitle;

  /// This method is so cool, it works with the [title] and makes it super cool. 
  void doSomeCoolThings() {}
}

We can reference attributes, methods, other classes inside our doc comments, by wrapping them inside [ and ] as you can see in the example above. These references will be converted to links inside the generated documentation. You can reference any class inside your project or even a method of a class.

Generate your documentation

Once we added the comments to our public API, we can generate the documentation. It is an automatic process when you publish it on pub.dev. If we are not working on a public package, we can generate the documentation manually. Before Flutter 2.10 and Dart 2.16, we could use the dartdoc command-line tool. From Dart 2.16, this tool has been moved under the main dart command, so we can invoke it by running dart doc. Unfortunately, in Dart 2.16, and 2.16.1, it has a bug, which may be fixed in the upcoming 2.16.2 release. Until then we can still use dartdoc if we have an earlier version.

cd your_package
dartdoc .

Or when we are building a Flutter package and the tool does not find the Flutter SDK:

FLUTTER_ROOT=/path/to/flutter/sdk dartdoc .

The generated documentation will be in the docs/api directory and it will look something like this.

Additional options

You have plenty of options to customize the generation. You have to create a dartdoc_options.yaml in the root of your package. Let me highlight some of its features.

Macros, templates

You can define templates and insert them in other places inside your doc comments. For example you can create a template for the author information:

/// {@template author_information}
/// Made by: David Tengeri <@dtengeri>
/// {@endtemplate}

And you can add this to your comments by inserting it as a macro:

/// My Awesome Library
/// {@macro author_information}
/// Details come here

Categories

You can define categories in the dartdoc_options.yaml. These categories can have their own page and they get a link in the left sidebar.

dartdoc:
  categories:
    "My Cool Category":
      markdown: doc/my_cool_category.md

Here, the md file contains the details of your category. You can mark a library, class or field with your category, so they will be listed on the summary page of the category.

/// {@category My Cool Category}
class MyAwesomeFeature {}

You can assign multiple categories to the same item.

Exclude

You can exclude any commented part from the documentation with the help of @nodoc.

/// This feature must not appear in the documentation.
///
/// {@nodoc}
class HiddenFeature {}

Image, animation, etc.

You have plenty of other options to improve your documentation, by adding images, video files, examples and other configurations. You can find all available options on the dartdoc package site.

Code organization

While I was working on some packages, I noticed a pattern in Flutter widgets about how they structure the fields and methods inside a class. After that I tried to stick to this approach as well, so the structure of the code in my packages will be familiar to Flutter devs.

In the widgets in the Flutter SDK, there is a doc comment for each class, which describe the intention of the widgets.

As I saw, the first item in the widget classes is the constructors. Each of them has doc comments, usually with usage examples.

After all constructors and factories come the list of attributes, nicely commented.

Then comes the build() method.

I think you can see the pattern. Since you usually create the widgets and don't call their methods, it is more valuable to have the constructors at the beginning of the class, so you can find how to use them easier.

Resources

You can find the source code of the sample package at https://github.com/dtengeri/dart_doc_example

You can use ScrollController when you want to manage the scrolling of a ListView. My first idea was to use the same controller for each list, but that won't work, it will not update the list that is not scrolled.

Another option would be to implement the synchronization by listening to changes on the controllers. But there is a great package that could help us and it is made by Google developers, the linked_scroll_controller.

Let's see how we can use it.

Let's say we have 2 horizontal list views below each other.

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key}) : super(key: key);

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(),
      body: SafeArea(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('Awesome list 1'),
            SizedBox(
              height: 150,
              // First list
              child: ListView.builder(
                scrollDirection: Axis.horizontal,
                itemBuilder: (context, index) => _ListItem(
                  index: index,
                ),
              ),
            ),
            const Divider(),
            const Text('Awesome list 2'),
            SizedBox(
              height: 150,
              // Second list
              child: ListView.builder(
                scrollDirection: Axis.horizontal,
                itemBuilder: (context, index) => _ListItem(
                  index: index,
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

class _ListItem extends StatelessWidget {
  const _ListItem({
    Key? key,
    required this.index,
  }) : super(key: key);
  final int index;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Center(
        child: Padding(
          padding: const EdgeInsets.all(8.0),
          child: Text('List item $index'),
        ),
      ),
    );
  }
}

This is how it looks like

Let's synchronize our lists.

First we need to add linked_scroll_controller to our dependencies in pubspec.yaml:

dependencies:
  linked_scroll_controller: ^0.2.0

Then we need to create the scroll controller group, which will manage the synchronization for us.

class _MyHomePageState extends State<MyHomePage> {
  // Create a new scoll controller group
  late final LinkedScrollControllerGroup _controllerGroup =
      LinkedScrollControllerGroup();
  // Create 2 new scroll controllers in the group, so they are connected.
  late final ScrollController _controller1 = _controllerGroup.addAndGet();
  late final ScrollController _controller2 = _controllerGroup.addAndGet();

  // ...
}

Then we just need to add the 2 controllers to our ListViews.

// ...
Column(
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    const Text('Awesome list 1'),
    SizedBox(
      height: 150,
      child: ListView.builder(
        // Use the controller
        controller: _controller1,
        scrollDirection: Axis.horizontal,
        itemBuilder: (context, index) => _ListItem(
          index: index,
        ),
      ),
    ),
    const Divider(),
    const Text('Awesome list 2'),
    SizedBox(
      height: 150,
      child: ListView.builder(
        // Use the controller
        controller: _controller2,
        scrollDirection: Axis.horizontal,
        itemBuilder: (context, index) => _ListItem(
          index: index,
        ),
      ),
    ),
  ],
),
// ...

This is how it works:

That's it!

You can find the source code at https://github.com/dtengeri/linked_list_views_example

But what happens when you have multiple applications and you want to use the same widgets? You can create a Flutter package, which can be shared amongst your project and with everyone else by publishing it on pub.dev.

When you develop your app to support multiple locales, your Flutter package should support that as well. Let's see how it works with the built-in solutions using the flutter_localizations and intl packages.

Basically, you can follow the great tutorial on flutter.dev about the localization of an application. We need to do the same with minor differences.

Prepare the package

First, let's create our Flutter package with

flutter create --template=package my_awesome_widgets

Let's add the required dependencies to pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.17.0

With the help of flutter_localizations and intl packages, Flutter can generate the localization classes based on your strings and translations. But we need to enable the code generation by extending the Flutter specific part in the pubspec.yaml file:

flutter:
  generate: true

Configure the code generation

The next step is to create the configuration file for the localization. It's name is l10n.yaml and it should be at the root of your Flutter project.

# This is the home of your localization files.
arb-dir: lib/l10n
# The name of the file where you define your translatable strings
template-arb-file: my_awesome_widgets_en.arb
# Your generated code will be placed to this directory
output-dir: lib/l10n/generated
# The name of the generated class 
output-class: MyAwesomeWidgetsLocalizations
# The file name for the generated code
output-localization-file: my_awesome_widgets_localizations.dart
# This tells Flutter where it should generate the code.
synthetic-package: false
# This tells the code generator to create nullable getters for our strings or not.
nullable-getter: false

The option that we will need for our package is the synthetic-package, which controls whether the generated code should go under .dart_tool or to the output directory defined in output-dir. Since we want to share our package, we will need to export it, so it should be in a place that can be added as an export statement.

Translatable strings

Let's define our translatable strings. Based on the configuration above, the base translation template is lib/l10n/my_awesome_widgets_en.arb. It is a JSON like file using the ICU format

{
  "appTitle": "My Awesome Widgets",
  "@appTitle": {
    "description": "This is the title of the application"
  }
}

All translatable string has key and optional meta information, which helps the translator and provide additional input for the code generator. We have lots of options like parameters, pluralization.

Using a placeholder

{
  "welcome": "Welcome {name}",
  "@welcome": {
    "description": "The welcome messge on the home page",
    "placeholders": {
      "name": {
        "type": "String"
      }
    }
  }
}

Pluralization

{
  "friendRequests": "{count, plural, =0{You have no new friend request} =1{You have one reuquest} other{You have {count} requests}}",
  "@friendRequests": {
    "description": "The number of pending friends requests",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Selection

You can define different strings based on the value of the input parameter. This could be useful for example for texts that are different for the genders in your language.

{
  "sendMessage": "{sex, select, male{Send him a message} female{Send her a message} other{Send a message}}",
  "@sendMessage": {
      "description": "Message on the send button",
      "placeholders": {
          "sex": {
            "type": "String"
          }
      }
  }
}

But the select is not restricted to only gender-based strings, you can use it for any input that requires a different string representation based on its content.

Number and date formatting

You can specify the format for numbers or dates in the arb file, so it will use the locale-specific version when it is displayed.

{
  "discountPrice": "Discount: {price}",
  "@discountPrice": {
    "placeholders": {
      "price": {
        "type": "double",
        "format": "currency"
      }
    }
  },
  "shippingDate": "Estimated shipping at {date}",
  "@shippingDate": {
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMMMd"
      }
    }
  }
}

Usage

So far we have the translation strings, we can generate the classes by running:

flutter gen-l10n

Which will output the following

Because l10n.yaml exists, the options defined there will be used instead.
To use the command line arguments, delete the l10n.yaml file in the Flutter project.

This will generate the MyAwesomeWidgetsLocalizations class under lib/l10n/generated. Let's export the class by adding the following line to lib/my_awesome_widgets.dart

export 'l10n/generated/my_awesome_widgets_localizations.dart';

Now we can use it in one of our cool widget

import 'package:flutter/material.dart';
import 'package:my_awesome_widgets/my_awesome_widgets.dart';

class CoolTexts extends StatelessWidget {
  const CoolTexts({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text(MyAwesomeWidgetsLocalizations.of(context).appTitle),
        Text(MyAwesomeWidgetsLocalizations.of(context).welcome('John')),
        Text(MyAwesomeWidgetsLocalizations.of(context).friendRequests(0)),
        Text(MyAwesomeWidgetsLocalizations.of(context).friendRequests(1)),
        Text(MyAwesomeWidgetsLocalizations.of(context).friendRequests(2)),
        Text(MyAwesomeWidgetsLocalizations.of(context).sendMessage('male')),
        Text(MyAwesomeWidgetsLocalizations.of(context).sendMessage('female')),
        Text(
          MyAwesomeWidgetsLocalizations.of(context).sendMessage('unspecfied'),
        ),
        Text(
          MyAwesomeWidgetsLocalizations.of(context).discountPrice(20),
        ),
        Text(
          MyAwesomeWidgetsLocalizations.of(context)
              .shippingDate(DateTime.now()),
        ),
      ],
    );
  }
}

Add another locale

If you want to add another locale to your package, you have to create a new arb file next to the my_awesome_widgets_en.arb. For example a Hungarian translation will look like

{
  "appTitle": "My Awesome Widgets",
  "welcome": "Üdvözöllek {name}",
  "friendRequests": "{count, plural, =0{Nincs új követési kérésed} =1{Egy új követési kérésed van} other{{count} követési kérésed van}}",
  "sendMessage": "{sex, select, male{Küldj neki egy üzenetet} female{Küldj neki egy üzenetet} other{Küldj neki egy üzenetet}}",
  "discountPrice": "Akciós ár: {price}",
  "shippingDate": "Tervezett szállítási dátum {date}"
}

It is fine to have only the strings in your other locales, you don't have to repeat the meta-information.

Running flutter gen-l10n will create a class for the Hungarian translation next to the English version.

Use the package in a Flutter application

Once we have our package with the shareable widgets, we can use it as a dependency in our Flutter applications. The only thing we have to do is to add the localization delegate to our application, so the localization SDK will know how to create the `` for each locales.

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:my_awesome_widgets/my_awesome_widgets.dart';

class MyAwesomeApp extends StatelessWidget {
  const MyAwesomeApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: const [
        // Add the localization delegate of your package
        MyAwesomeWidgetsLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
      ],
      supportedLocales: const [
        Locale('en'),
        Locale('hu'),
      ],
      home: Scaffold(
        appBar: AppBar(),
        body: const Center(
          child: CoolTexts(),
        ),
      ),
    );
  }
}

English	Hungarian

Testing the package

We want to share a reliable package that is not sensitive to changes we make by adding new features. So we add tests to our package. In order to test the widgets that use locales, you have to provide the same environment for them as they would be used in a real app. This means you have to provide a MaterialApp and the delegates as well.

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

import 'package:my_awesome_widgets/my_awesome_widgets.dart';

void main() {
  group('CoolTexts', () {
    testWidgets('displays the texts', (tester) async {
      await tester.pumpWidget(
        const MaterialApp(
          // Add the delegates defined by our package
          localizationsDelegates:
              MyAwesomeWidgetsLocalizations.localizationsDelegates,
          home: Scaffold(
            // Add our widget that we want to test
            body: CoolTexts(),
          ),
        ),
      );
      // Check it works correctly
      expect(find.text('Welcome John'), findsOneWidget);
    });
  });
}

Summary

This article became longer than I expected. My goal was to show how to add locales to your Flutter package and how can you use it in your applications. Feel free to leave your thoughts in the comment section.

Resources

• Github repository of the sample package and application
• i18n user guide
• A Guide to Flutter Localization