🦊 Foxtail 🌐

A Ruby implementation of Project Fluent - a modern localization system designed to improve how software is translated.

Features

• fluent.js compatibility - 159/160 official test fixtures passing
• Runtime message formatting - Bundle system with icu4x-based formatting
• FTL syntax parser - Syntax support with error recovery
• Multi-language support - Number, date, and pluralization formatting
• CLI tools - Lint and validate FTL files
• Ruby implementation - API following Ruby conventions

Installation

Add this line to your application's Gemfile:

gem "foxtail"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install foxtail

Quick Start

icu4x Gem Setup

Foxtail uses the icu4x gem (Ruby bindings for ICU4X), which requires data configuration:

1. The icu4x-data-recommended gem is included as a development dependency
2. Run bin/setup to configure the ICU4X_DATA_PATH environment variable in .env

For details, see the icu4x gem documentation.

Basic Usage

require "foxtail"
require "icu4x"

resource = Foxtail::Resource.from_string(<<~FTL)
  hello = Hello, { $name }!
  emails =
      You have { $count ->
          [one] one email
         *[other] { $count } emails
      }.
FTL

bundle = Foxtail::Bundle.new(ICU4X::Locale.parse("en-US"))
bundle.add_resource(resource)

bundle.format("hello", name: "Alice")
# => "Hello, Alice!"

bundle.format("emails", count: 1)
# => "You have one email."

bundle.format("emails", count: 5)
# => "You have 5 emails."

More Examples

See the examples/ directory for executable demonstrations:

• Basic features: Variables, selectors, terms, attributes
• Number/Date formatting: Currency, percent, date styles
• Custom functions: Adding your own formatters
• Multi-language apps: Language fallback with Sequence
• E-commerce: Real-world pricing and cart localization
• Dungeon Game: Advanced item localization with grammatical gender/case (German), elision (French), and counter words (Japanese)

Development

After checking out the repo, run:

$ bin/setup

This will install dependencies and set up the fluent.js submodule for compatibility testing.

Running Tests

# Run all tests
$ bundle exec rake spec

Code Quality

# Run all checks (tests + linting)
$ bundle exec rake

Architecture

• Parser System - FTL syntax parsing and AST implementation
• Bundle System - Runtime message formatting with icu4x integration
• Sequence - Language fallback chains

See doc/architecture.md for detailed design documentation.

CLI

Foxtail provides command-line tools for working with FTL files:

• foxtail check - Check FTL files for syntax errors
• foxtail dump - Dump FTL files as AST in JSON format
• foxtail ids - Extract message and term IDs
• foxtail tidy - Format FTL files with consistent style

See doc/cli.md for full documentation.

Compatibility

• Ruby: 3.2 or higher
• fluent.js: 159/160 test fixtures passing (99.4%)
  • Syntax parser: 97/98 (99.0%)
  • Bundle parser: 62/62 (100%)

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sakuro/foxtail.

1. Fork it
2. Create your feature branch (git checkout -b feature/add-some-feature)
3. Run the tests (bundle exec rake spec)
4. Commit your changes (git commit -am ':sparkles: Add some feature')
5. Push to the branch (git push origin feature/add-some-feature)
6. Create new Pull Request

Acknowledgments

This project stands on the shoulders of giants:

• ICU4X: Number, date/time, plural rules, and locale handling
• Fluent Project: Foxtail aims for compatibility with Mozilla's Fluent localization system, particularly fluent.js (Apache 2.0)

License

The gem is available as open source under the terms of the MIT License.