English | Chinese

basic_message

A structured, type-safe, and compile-time mapping localization framework for Dart, specifically designed for multi-environment projects (Flutter GUI and Dart CLI). It enables "Define Once, Use Everywhere" by decoupling business logic from platform-specific translation implementations.

Why basic_message?

Building a full-stack Dart/Flutter project often leads to fragmented localization management. basic_message solves these common pain points:

• Unified Definition: Define messages in a shared package; reuse them seamlessly across CLI, GUI, and Server.
• Type Safety: Leverage Dart enum and Generics to catch missing translation keys at compile-time.
• Platform Decoupling: Use a unified MessageProvider interface to bridge the gap between context-dependent Flutter apps and context-free CLI tools.
• ARB Standard: Native support for the ARB (Application Resource Bundle) format, ensuring compatibility with professional translation platforms.
• Zero Runtime Overhead: Utilize code generation to bind keys, maintaining high performance in both GUI and CLI environments.
• Sophisticated Rendering: Built-in support for dynamic parameters, plurals, and gender-based localization, abstracting the complexity of the intl package.

Quick Start

Core Workflow

1. Define: Create a shared MessageEnum in a central package.
2. Generate: Extract ARB files for translation management.
3. Integrate: Implement a platform-specific MessageProvider.
4. Execute: Use MessageEngine.tr() to dispatch translations anywhere in your app.

1. Installation

dart pub add basic_message

2. Define Messages (Shared Package)

Create a dedicated package (e.g., share_message) to hold your message definitions.

# packages/share_message/pubspec.yaml
dependencies:
  basic_message: ^1.0.0

// packages/share_message/lib/src/share_message_base.dart
import 'package:basic_message/basic_message.dart';

enum AppMessage implements MessageEnum {
  welcomeLabel(
    1001,
    'home_index_header_welcome_label',
    'Welcome, {username}!',
    'Personalized welcome message',
    param: {'username': 'Guest'},
  );
  
  // ... implement MessageEnum interface (code, key, msg, param, desc)

  @override
  final int code;
  @override
  final String key;
  @override
  final String msg;
  @override
  final Map<String, Object> param;
  @override
  final String desc;

  const AppMessage(
    this.code,
    this.key,
    this.msg,
    this.desc, {
    this.param = const {},
  });
}

3. Generate ARB Resources

Use the provided CLI tools to bridge your enums and the standard intl pipeline:

1. dart run basic_message:gen_msg_resource — Generates intermediate resource classes.
2. dart run intl_translation:extract_to_arb — Extracts the ARB files for your translation team.
3. Translate the ARB files, then run generate_from_arb to create the localized Dart code.

(For full automation, see our Design Guide and the Example Repository).

4. CLI Integration

Step: Add the shared message package dependency, copy the CliMessageProvider boilerplate from the Example Repository, and initialize MessageEngine in your main() entry point.

// Conceptual snippet: please refer to 'cli_example' for the full implementation
import 'package:basic_message/basic_message.dart';

void main() {
  MessageEngine.init(CliMessageProvider('en'));
  print(MessageEngine.tr(AppMessage.welcomeLabel, args: {'username': 'Alice'}));
}

5. Flutter Integration

Step: Add the shared message package dependency, run flutter gen-l10n, copy the GuiMessageProvider boilerplate and registry generator from the Example Repository, and initialize MessageEngine within a Builder to gain BuildContext access.

// Conceptual snippet: please refer to 'gui_example' for the full implementation
import 'package:flutter/material.dart';
import 'package:basic_message/basic_message.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    MessageEngine.init(GuiMessageProvider(context));
    return MaterialApp(
      home: Scaffold(
        body: Text(MessageEngine.tr(AppMessage.welcomeLabel)),
      ),
    );
  }
}

Resources

• Design Guide: Deep dive into architecture, workflows, and best practices.
• Naming Convention: Standardized four-level naming strategy for team consistency.
• Example Repository: A complete, ready-to-run boilerplate including share_message, cli_example, and gui_example.