stringlocale

https://pub.dev/packages/stringlocale
Admin
stringlocale allows developers to declare strings with typed parameters, compile them into offline...
Tokens:8,994
Snippets:126
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run Flutter Example

Source: https://pub.dev/packages/stringlocale

Navigates to the example directory and runs the Flutter application on macOS. This sample includes locale chips and imperative string resolution.

```bash
cd example
flutter run -d macos

```

--------------------------------

### Install stringlocale as a Global Executable

Source: https://pub.dev/packages/stringlocale/install

Use this command to install the stringlocale package globally, making its command-line executables available.

```bash
dart pub global activate stringlocale
```

--------------------------------

### Run Flutter macOS Sample

Source: https://pub.dev/packages/stringlocale

Navigate to the example directory and run the Flutter sample application on macOS. This command builds and launches the app for the macOS platform.

```bash
cd example
flutter run -d macos
```

--------------------------------

### Example App Development Tasks

Source: https://pub.dev/packages/stringlocale

Perform development tasks for the example application. This includes analyzing the Flutter code, running tests, and building a debug version of the macOS application.

```bash
cd example
flutter analyze
flutter test
flutter build macos --debug
```

--------------------------------

### Core Stringlocale Workflow Example

Source: https://pub.dev/packages/stringlocale/example

Demonstrates the complete stringlocale process: declaring strings with typed parameters, compiling them to offline locale bundles, and resolving them at runtime. This example uses OfflineDrafter for deterministic placeholders and runs without an API key. For production, consider using `dart run stringlocale compile --locales ... --out assets/i18n`.

```dart
// Demonstrates the core stringlocale workflow:
//   1. Declare strings once with typed params
//   2. Compile to target locales (offline, no API key needed)
//   3. Resolve at runtime — pure offline lookup, no network call
//
// Run with: dart run example/lib/main.dart
//
// For LLM-drafted translations, set OPENROUTER_API_KEY and remove the
// drafter: argument — the compiler picks it up automatically.

import 'package:stringlocale/compile.dart';
import 'package:stringlocale/stringlocale.dart';

// 1. Declare strings once -------------------------------------------------

final welcome = StringLocale(
  'Welcome back, {name}! You have {count} new messages.',
  id: 'welcome',
  params: {
    'name': Param.literal(),
    'count': Param.plural(),
  },
  gendered: true, // generates male/female/other variants per locale
);

final orderTotal = StringLocale(
  '{name} placed an order for {amount}',
  id: 'order_total',
  params: {
    'name': Param.literal(),
    'amount': Param.currency('USD'),
  },
);

final strings = [welcome, orderTotal];
int registerAll() => strings.length;

// 2. Compile & resolve ----------------------------------------------------

Future<void> main() async {
  registerAll();

  const outDir = '.dart_tool/stringlocale_example';
  const locales = ['en-US', 'es-ES', 'fr-FR', 'ar-SA', 'hi-IN'];

  // OfflineDrafter emits deterministic placeholders so this runs without a key.
  // In production use: dart run stringlocale compile --locales ... --out assets/i18n
  final result = await compileStrings(
    strings: strings,
    locales: locales,
    drafter: OfflineDrafter(),
    sourceLocale: 'en-US',
    existingDir: outDir,
  );
  result.writeSplit(outDir);

  load(outDir, locale: 'en-US');

  // 3. Resolve at runtime — no API call, no network ----------------------
  for (final locale in locales) {
    setLocale(locale);
    print('--- $locale ---');
    print(welcome.resolve(args: {'name': 'Sofia', 'count': 3, 'gender': 'female'}));
    print(orderTotal.resolve(args: {'name': 'Sofia', 'amount': 149.99}));
    print('');
  }
}

```

--------------------------------

### Example pubspec.yaml Dependency

Source: https://pub.dev/packages/stringlocale/install

This is an example of how the stringlocale dependency will appear in your project's pubspec.yaml file after running `flutter pub add stringlocale`.

```yaml
dependencies:
  stringlocale: ^0.4.0
```

--------------------------------

### Resolve Strings at Runtime

Source: https://pub.dev/packages/stringlocale

Load the compiled bundles and use the stringlocale API to resolve localized strings based on the current locale. This example demonstrates resolving a string with a plural parameter.

```dart
import 'package:stringlocale/stringlocale.dart';
import 'strings.dart';

void main() {
  registerAll();
  final bundle = Bundle.fromDir('assets/i18n', ioFileReader);
  useBundle(bundle, locale: 'es-ES');

  print(inbox.resolve(args: {'count': 5}));
  // → "Tienes 5 mensajes."
}

```

--------------------------------

### Run Minimal Console Sample

Source: https://pub.dev/packages/stringlocale

Execute the minimal console sample application. This sample does not require an API key and runs quickly.

```dart
dart run example/lib/main.dart
```

--------------------------------

### Run Full Console Sample

Source: https://pub.dev/packages/stringlocale

Execute the full console sample application, which includes all parameter types. This sample demonstrates comprehensive usage.

```dart
dart run example/main.dart
```

--------------------------------

### Display CLI Help

Source: https://pub.dev/packages/stringlocale

Show the help information for the stringlocale command-line interface. This is useful for understanding available commands and options.

```bash
dart run stringlocale --help
```

--------------------------------

### Initialize and Use Bundle in Plain Dart

Source: https://pub.dev/packages/stringlocale

Sets up stringlocale for plain Dart applications by registering bundles and using the .resolve() method for string localization. Falls back to source strings if no bundle is loaded.

```dart
import 'package:stringlocale/stringlocale.dart';

import 'strings.dart';

void main() {
  registerAll();

  final bundle = Bundle.fromDir('assets/i18n', ioFileReader);
  useBundle(bundle, locale: 'ne-NP');

  final text = fee.resolve(args: {
    'creator': 'Jane Doe',
    'amount': 2500,
  });

  print(text);
}

```

--------------------------------

### Check for String Drift and Untranslated Warnings

Source: https://pub.dev/packages/stringlocale

Imports current strings and compiled bundles to report drift, including missing, orphaned, stale entries, placeholder drift, and untranslated warnings. Exits non-zero on problems, suitable for CI.

```bash
dart run stringlocale check \
  --input lib/strings.dart \
  --register registerAll \
  --out assets/i18n
```

--------------------------------

### Compile Strings to Locales

Source: https://pub.dev/packages/stringlocale

Use the stringlocale CLI to compile your source strings into locale-specific bundles. Configure API keys and endpoints as needed. This command generates manifest and bundle JSON files.

```bash
# Default endpoint is OpenRouter; point STRINGLOCALE_BASE_URL elsewhere for any
# other OpenAI-compatible provider.
export STRINGLOCALE_API_KEY=sk-...
# export STRINGLOCALE_BASE_URL=https://api.openai.com/v1/chat/completions
# export STRINGLOCALE_MODEL=gpt-4o-mini

dart run stringlocale compile \
  --locales en-US,es-ES,fr-FR,ar-SA \
  --source-locale en-US \
  --out assets/i18n

```

--------------------------------

### Regenerate Flutter Sample Assets

Source: https://pub.dev/packages/stringlocale

Compile Flutter sample assets using the stringlocale CLI. This command generates locale bundles for Flutter applications, specifying input files, registration functions, locales, output directories, and the drafter mode.

```bash
dart run stringlocale compile \
  --input example/lib/flutter_strings.dart \
  --register registerFlutterSampleStrings \
  --locales en-US,hi-IN,ne-NP,nl-NL,fr-FR,ru-RU \
  --source-locale en-US \
  --out example/assets/i18n \
  --drafter offline
```

--------------------------------

### Keep Bundles in Sync

Source: https://pub.dev/packages/stringlocale

Use stringlocale CLI commands to check for drift between your source strings and compiled bundles, or to prune unused translations. The 'check' command is suitable for CI gates.

```bash
dart run stringlocale check --out assets/i18n          # CI gate — exits non-zero on drift
dart run stringlocale prune --out assets/i18n --dry-run
dart run stringlocale prune --out assets/i18n

```

--------------------------------

### Compile Strings and Draft Translations

Source: https://pub.dev/packages/stringlocale

Compiles Dart strings, registers them, drafts translations for specified locales, and writes bundles to the output directory. Use `--combined` to emit a single bundle file.

```bash
dart run stringlocale compile \
  --input lib/strings.dart \
  --register registerAll \
  --source-locale en-US \
  --locales ne-NP,nl-NL,ar-SA \
  --out assets/i18n
```

```json
{
  "translation": {
    "drafter": "llm",
    "model": "google/gemini-2.5-flash"
  }
}
```

```bash
dart run stringlocale compile \
  --locales en-US,ne-NP,nl-NL \
  --source-locale en-US \
  --combined assets/i18n/bundle.json
```

--------------------------------

### Import stringlocale Modules

Source: https://pub.dev/packages/stringlocale

Import the core stringlocale library for runtime and declarations. Optionally import Flutter widgets or the compiler API.

```dart
import 'package:stringlocale/stringlocale.dart'; // runtime and declarations
import 'package:stringlocale/flutter.dart';       // Flutter widgets (optional)
import 'package:stringlocale/compile.dart';        // compiler API and build scripts

```

--------------------------------

### Load StringLocale Bundle with Custom User Adapted Adapter

Source: https://pub.dev/packages/stringlocale

Loads a StringLocale bundle from 'assets/i18n' for the 'ne-NP' locale. It configures realtime user adaptation and provides a custom adapter function to process the input value, locale, and context.

```dart
import 'package:stringlocale/stringlocale.dart';

final bundle = load(
  'assets/i18n',
  locale: 'ne-NP',
  userAdaptedMode: UserAdaptedMode.realtime,
  adapter: (value, locale, context) {
    // Implement your own service call here.
    return '$locale: $value';
  },
);
```

--------------------------------

### Load StringLocale Bundles from Assets

Source: https://pub.dev/packages/stringlocale

Loads generated split bundles from the app's assets directory. This function parses the manifest and merges all bundle files into a single Bundle object.

```dart
import 'dart:convert';

import 'package:flutter/services.dart';
import 'package:stringlocale/flutter.dart';

Future<Bundle> loadBundleFromAssets(String assetDir) async {
  final manifest = jsonDecode(
    await rootBundle.loadString('$assetDir/manifest.json'),
  ) as Map<String, dynamic>;
  final files = manifest['files'] as Map;

  Bundle? bundle;
  for (final entry in files.values.cast<Map>()) {
    final data = jsonDecode(
      await rootBundle.loadString('$assetDir/${entry['path']}'),
    ) as Map<String, dynamic>;
    if (bundle == null) {
      bundle = Bundle(data);
    } else {
      bundle.merge(data);
    }
  }

  if (bundle == null) throw StateError('No stringlocale bundles found');
  return bundle;
}

```

--------------------------------

### Package Development Tasks

Source: https://pub.dev/packages/stringlocale

Perform standard development tasks for the stringlocale package. This includes code formatting, static analysis, running tests, and performing a dry run of publishing to pub.dev.

```bash
dart format .
flutter analyze
flutter test
dart pub publish --dry-run
```

--------------------------------

### Compile Locales using CLI

Source: https://pub.dev/packages/stringlocale

Use the stringlocale CLI to compile translation files for specified locales. This command generates offline locale bundles.

```bash
dart run stringlocale compile \
  --locales es-ES,fr-FR,hi-IN,ja-JP,ar-SA \
  --source-locale en-US \
  --out assets/i18n

```

--------------------------------

### Declare StringLocales with Parameters

Source: https://pub.dev/packages/stringlocale

Define StringLocale instances with placeholders and specify parameter types like number, plural, literal, and currency. Mismatched placeholders and params will throw an error during construction.

```dart
// lib/strings.dart
import 'package:stringlocale/stringlocale.dart';

final followers = StringLocale(
  '{n} followers',
  id: 'followers',
  params: {'n': Param.number()},
);

final inbox = StringLocale(
  'You have {count} messages',
  id: 'inbox',
  params: {'count': Param.plural()},
);

final fee = StringLocale(
  '{creator} charges {amount} per post',
  id: 'fee',
  params: {
    'creator': Param.literal(),
    'amount': Param.currency('NPR'),
  },
);

final greeting = StringLocale(
  '{name}, your account is ready',
  id: 'greeting',
  params: {'name': Param.literal()},
  gendered: true,
);

final allStrings = [followers, inbox, fee, greeting];
int registerAll() => allStrings.length;

```

--------------------------------

### Declare a String with Typed Parameters

Source: https://pub.dev/packages/stringlocale

Define a string with placeholders and specify their types (literal, plural, gendered). This is the initial declaration before compilation.

```dart
final welcome = StringLocale(
  'Welcome back, {name}! You have {count} new messages.',
  id: 'welcome',
  params: {
    'name': Param.literal(),
    'count': Param.plural(),
  },
  gendered: true,
);

```

--------------------------------

### Add stringlocale as a Flutter Project Dependency

Source: https://pub.dev/packages/stringlocale/install

Run this command in your Flutter project to add stringlocale as a dependency. This command automatically updates your pubspec.yaml file and fetches the package.

```bash
$ flutter pub add stringlocale
```

--------------------------------

### Add stringlocale as a Dart Project Dependency

Source: https://pub.dev/packages/stringlocale/install

Run this command in your Dart project to add stringlocale as a dependency. This command automatically updates your pubspec.yaml file and fetches the package.

```bash
dart pub add stringlocale
```

--------------------------------

### Switch Locale in Flutter

Source: https://pub.dev/packages/stringlocale

Demonstrates how to imperatively change the application's locale using the StringLocaleScope controller within a Flutter application.

```dart
StringLocaleScope.of(context).setLocale('fr-FR');

```

--------------------------------

### Declare Asset Directory in pubspec.yaml

Source: https://pub.dev/packages/stringlocale

Specify the directory containing your compiled stringlocale bundles in the Flutter app's pubspec.yaml file.

```yaml
flutter:
  assets:
    - assets/i18n/

```

--------------------------------

### Add stringlocale Dependency

Source: https://pub.dev/packages/stringlocale

Add the stringlocale package to your pubspec.yaml file to include it in your project dependencies.

```yaml
dependencies:
  stringlocale: ^0.3.0

```

--------------------------------

### Define User Adapted Parameter for Creator Bio

Source: https://pub.dev/packages/stringlocale

Marks a 'bio' parameter as user-adapted, providing context for custom adaptation. This is used when defining a StringLocale for a creator's profile biography.

```dart
final profileBio = StringLocale(
  'Creator bio: {bio}',
  id: 'profile_bio',
  params: {
    'bio': Param.userAdapted(
      context: 'Short creator profile shown to shoppers',
    ),
  },
);
```

--------------------------------

### Resolve StringLocale with User-Provided Text

Source: https://pub.dev/packages/stringlocale

Resolves the 'profileBio' StringLocale by providing user-specific arguments for the 'bio' parameter. This demonstrates how to pass dynamic user text into a localized string.

```dart
final out = profileBio.resolve(args: {
  'bio': '1200 followers, vintage camera collector, ships on Fridays',
});
```

--------------------------------

### Wrap App with StringLocaleScope and Use Tr Widget

Source: https://pub.dev/packages/stringlocale/versions/0.4.0

Wraps your Flutter app with StringLocaleScope to provide locale and bundle context. Renders localized strings using the Tr widget, supporting arguments for dynamic content.

```dart
import 'package:flutter/material.dart';
import 'package:stringlocale/flutter.dart';

import 'strings.dart';

class App extends StatelessWidget {
  const App({super.key, required this.bundle});

  final Bundle bundle;

  @override
  Widget build(BuildContext context) {
    return StringLocaleScope(
      locale: 'ne-NP',
      bundle: bundle,
      child: Builder(
        builder: (context) => Column(
          children: [
            Tr(greeting, args: {'name': 'Anisha', 'gender': 'female'}),
            Tr(inbox, args: {'count': 5}),
            FilledButton(
              onPressed: () {
                final label = tr(context, fee, args: {
                  'creator': 'Anisha',
                  'amount': 2500,
                });
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text(label)),
                );
              },
              child: const Text('Show'),
            ),
          ],
        ),
      ),
    );
  }
}

```

--------------------------------

### Prune Orphaned Entries from Bundle

Source: https://pub.dev/packages/stringlocale

Removes orphaned entries (IDs in the bundle but not in code) without redrafting. Use `--dry-run` to preview removals before execution.

```bash
dart run stringlocale prune --out assets/i18n --dry-run
```

```bash
dart run stringlocale prune --out assets/i18n
```

--------------------------------

### Flutter App Widget with StringLocaleScope

Source: https://pub.dev/packages/stringlocale

Wraps the application with StringLocaleScope to provide locale and bundle context. Renders localized strings using the Tr widget and imperative tr() function.

```dart
import 'package:flutter/material.dart';
import 'package:stringlocale/flutter.dart';

import 'strings.dart';

class App extends StatelessWidget {
  const App({super.key, required this.bundle});

  final Bundle bundle;

  @override
  Widget build(BuildContext context) {
    return StringLocaleScope(
      locale: 'ne-NP',
      bundle: bundle,
      child: Builder(
        builder: (context) => Column(
          children: [
            Tr(greeting, args: {'name': 'Anisha', 'gender': 'female'})
            Tr(inbox, args: {'count': 5}),
            FilledButton(
              onPressed: () {
                final label = tr(context, fee, args: {
                  'creator': 'Anisha',
                  'amount': 2500,
                });
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text(label)),
                );
              },
              child: const Text('Show'),
            ),
          ],
        ),
      ),
    );
  }
}

```

--------------------------------

### Import stringlocale in Dart Code

Source: https://pub.dev/packages/stringlocale/install

Include this import statement in your Dart files to use the stringlocale package's functionality.

```dart
import 'package:stringlocale/stringlocale.dart';
```

--------------------------------

### Resolve a String at Runtime

Source: https://pub.dev/packages/stringlocale

Resolve a declared string with provided arguments, including dynamic values for parameters like name, count, and gender. The resolution is an offline lookup.

```dart
welcome.resolve(args: {'name': 'Sofia', 'count': 3, 'gender': 'female'})
// Spanish → "¡Bienvenida, Sofia! Tienes 3 mensajes nuevos."
// Arabic  → "مرحباً بعودتك، Sofia! لديك ٣ رسائل جديدة."
// Hindi   → "वापसी पर स्वागत है, Sofia! आपके 3 नए संदेश हैं।"

```

--------------------------------

### Declare a Localizable String

Source: https://pub.dev/packages/stringlocale

Define a StringLocale instance in your Dart code, specifying the template, an ID, and any parameters like plurals. Ensure lazy finals are initialized.

```dart
// lib/strings.dart
import 'package:stringlocale/stringlocale.dart';

final inbox = StringLocale(
  'You have {count} messages',
  id: 'inbox',
  params: {'count': Param.plural()},
);

// Force lazy top-level finals to initialize; return value is the string count.
int registerAll() => [inbox].length;

```

--------------------------------

### StringLocale with Custom Axes

Source: https://pub.dev/packages/stringlocale

Define custom axes for any other variant type, such as 'audience', by specifying the axis name and its possible values.

```dart
final cta = StringLocale(
  '{name}, your workspace is ready',
  id: 'workspace_ready',
  params: {'name': Param.literal()},
  axes: {
    'audience': ['buyer', 'seller'],
  },
  required: ['audience'],
);

```

--------------------------------

### Resolve String with Specific Locale in Plain Dart

Source: https://pub.dev/packages/stringlocale

Allows specifying a locale directly in the .resolve() call for individual string lookups in plain Dart. This overrides the globally set locale for that specific resolution.

```dart
final text = inbox.resolve(
  locale: 'ja-JP',
  args: {'count': 5},
);

```

--------------------------------

### StringLocale with Gendered Axis

Source: https://pub.dev/packages/stringlocale

Use `gendered: true` to enable the built-in `gender` axis for translations that vary based on gender.

```dart
final message = StringLocale(
  '{name} has {count} saved campaigns',
  id: 'saved_campaigns',
  params: {
    'name': Param.literal(),
    'count': Param.plural(),
  },
  gendered: true,
);

```
Tokens:
Raw