中文文档

Flutter String Extractor Plugin Usage Guide

This is a Flutter plugin for IntelliJ IDEA / Android Studio designed to help developers quickly extract hard-coded strings into ARB files and automatically replace them with localization code calls.

✨ Core Features

• Smart Extraction: Supports extracting both simple strings and strings with interpolation (e.g., "Hello $name").
• Batch Extraction: Extract all strings in the current file at once with a powerful review dialog.
• Automatic Conversion: Automatically converts Dart interpolation syntax ($name) into ARB placeholder format ({name}).
• Batch Update: Automatically identifies and updates all .arb files in the specified directory (e.g., updating both app_en.arb and app_zh.arb simultaneously), saving you the trouble of manually copying keys.
• Highly Configurable: Supports customizing the ARB file directory, the generated localization class name, and the preferred lookup file.

⚙️ Project Configuration (pubspec.yaml)

To let the plugin know where your ARB files are located and which localization class you are using (e.g., S or AppLocalizations), please add a flutter_string_extractor configuration section to your project's pubspec.yaml.

If not configured, the plugin will use the following default values:

• Directory: lib/l10n
• Class Name: S

Complete Configuration Example

# pubspec.yaml

# ... other dependencies ...

# Plugin Configuration
flutter_string_extractor:
  # [Optional] The directory path where ARB files are located (relative to the project root)
  # The plugin will scan all .arb files in this directory and write to them simultaneously
  arb_dir: lib/src/l10n

  # [Optional] The class name used when generating code
  # For example, if set to AppLocalizations, the replacement code will be: AppLocalizations.of(context).keyName
  localizations_class_name: S
  
  # [Optional] Specify a preferred ARB file to lookup existing keys.
  # If set, the plugin will only search this file for existing values to reuse keys.
  lookup_arb_file: app_en.arb

  # [Optional] Use extension mode for code generation (e.g., context.l10n.keyName)
  # Default: false
  use_extension: true

  # [Optional] The name of the extension (default: l10n)
  # Resulting code: context.l10n.keyName
  extension_name: l10n

  # [Optional] The import path for the extension
  # If provided, the plugin will automatically add this import to the file if it doesn't exist
  extension_import_path: package:example_app/l10n/l10n_extension.dart

🚀 How to Use

The plugin provides three convenient ways to use it:

Method 1: Intention Action (Recommended 👍)

This is the fastest way for single string extraction.

1. Place your cursor inside a string literal in your Dart code (e.g., "Click me").
2. Press Alt + Enter (Windows/Linux) or Option + Enter (macOS).
3. Select "Extract string to ARB file" from the popup menu.
4. Enter the Key name in the dialog box (the plugin will automatically suggest a name based on the string content).
5. Press Enter to confirm. The plugin will automatically replace the code and update the ARB files.

Method 2: Extract All Strings (New ✨)

Batch extract all strings in the current file.

1. Right-click in the editor and select "Extract All Strings to ARB".
2. A dialog will appear listing all string literals found in the file.
3. Review & Edit:
   • Edit Keys: Directly modify the keys in the table.
   • Batch Update: Check "Batch update keys for same values" to update keys for identical strings simultaneously.
   • Copy/Paste: Supports multi-cell copy and paste (compatible with Excel/Sheets).
   • Navigate: Double-click on the "Original Text" to jump to the source code.
   • Exclude: Select rows and press Backspace to clear the key (these entries will be skipped) or use the toolbar to remove them.
4. Click OK. The plugin will batch write to ARB files and replace the code.

Method 3: Menu Action

1. Select the string you want to extract (or simply place the cursor on the string).
2. Right-click in the editor, or look for the Action provided by the plugin in the top menu bar (usually under the Refactor menu, or use the shortcut Alt + S).
3. Enter the Key name and confirm.

💡 Feature Details

1. Automatic Interpolation and Metadata (@key)

The plugin intelligently handles Dart string interpolation and generates necessary metadata.

• Source Code: "Total cost: ${price * count}"
• Extracted ARB Value: "Total cost: {priceCount}"
• Generated ARB Metadata:

  "@total_cost": {
    "placeholders": {
      "priceCount": {
        "type": "int"
      }
    }
  }

• Generated Dart Code: context.l10n.total_cost (assuming Extension Mode is enabled)

Smart Type Inference: The plugin automatically infers the placeholder type based on the Dart expression:

• int: Arithmetic operators (+, -, *, %, ~/) or properties like .length, .size, .count, .index.
• double: Division operator (/).
• String: Default for all other cases.

2. Extension Mode Support (New ✨)

Instead of the traditional S.of(context).key syntax, you can enable Extension Mode to use a more concise syntax: context.l10n.key.

• Auto-Import: If extension_import_path is configured, the plugin will automatically add the necessary import statement at the top of your Dart file.
• Customizable: Change l10n to any name you prefer (e.g., context.intl.key).

3. Multi-language Synchronization

If multiple files exist in your arb_dir directory:

• app_en.arb
• app_vi.arb
• app_zh.arb

When you extract a string, the plugin will write the same Key and Value to all files simultaneously. This ensures that keys remain synchronized across all supported locales, even if you haven't translated them yet.

4. Smart Key Lookup

With the lookup_arb_file configuration, you can specify a primary language file. When extracting strings, the plugin will prioritize checking this file. If a matching string value is found, it will automatically reuse the existing Key to prevent duplicate entries in your ARB files.

4. Undo Support

All file modifications (ARB files and Dart code) support the standard IDE Undo operation (Ctrl+Z / Cmd+Z).

License

This project is licensed under the MIT License - see the LICENSE file for details.