i18n-message_format 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ba2dc552b6ed476c92dc2eb3e79643d1820e0b9ac3648efabceecbc2205700a
+  data.tar.gz: ac841cf20af045dbfa54619a8f37181e8770e2a1667c2401a3c9431bb1bc8980
+SHA512:
+  metadata.gz: d4b201b2ab2f751d15d29c7bf4b57e905b13aead055912d02d6219e7f7b342f86e8543f7b68b874730f237f23b4c6767787feab981741d43f1c8aa27738d3d98
+  data.tar.gz: 3ba0a787f483e48c5c3843705a62065b7b8416351a12c15a7241b717f81cd3d3184cb6aabda4b05869954a852420a49a70847764a0414a5fc6eab2e46c0714cf

data/.envrc

@@ -0,0 +1,10 @@
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+# `use devenv` supports the same options as the `devenv shell` command.
+#
+# To silence the output, use `--quiet`.
+#
+# Example usage: use devenv --quiet --impure --option services.postgres.enable:bool true
+use devenv

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-02-25
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Chris Fung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# I18n::MessageFormat
+
+ICU Message Format support for the Ruby [i18n](https://github.com/ruby-i18n/i18n) gem. Pure Ruby parser, no native dependencies.
+
+## Installation
+
+```bash
+bundle add i18n-message_format
+```
+
+## Usage
+
+### Standalone
+
+```ruby
+require "i18n/message_format"
+
+I18n::MessageFormat.format(
+  "{name} has {count, plural, one {# item} other {# items}}",
+  name: "Alice", count: 3
+)
+# => "Alice has 3 items"
+```
+
+### With I18n Backend
+
+Store your Message Format strings in separate YAML files:
+
+```yaml
+# config/locales/mf/en.yml
+en:
+  greeting: "Hello {name}!"
+  items: "{count, plural, one {# item} other {# items}}"
+```
+
+Configure the backend:
+
+```ruby
+I18n.backend = I18n::Backend::Chain.new(
+  I18n::MessageFormat::Backend.new("config/locales/mf/*.yml"),
+  I18n::Backend::Simple.new
+)
+
+I18n.t("greeting", name: "Alice")
+# => "Hello Alice!"
+```
+
+### Supported Syntax
+
+- Simple arguments: `{name}`
+- Number format: `{count, number}`
+- Date format: `{d, date, short}`
+- Time format: `{t, time, short}`
+- Plural: `{count, plural, one {# item} other {# items}}`
+- Select: `{gender, select, male {He} female {She} other {They}}`
+- Selectordinal: `{pos, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`
+- Nested messages
+- Escaped braces: `'{ '} ''`
+
+### Number, Date, and Time Formatting
+
+Number, date, and time format arguments delegate to [`I18n.localize`](https://www.rubydoc.info/gems/i18n/I18n/Backend/Base#localize-instance_method), so their output depends on the format definitions in your I18n backend.
+
+- **Number** — `{count, number}` calls `I18n.localize` with the value and locale. The optional style (e.g. `{count, number, integer}`) is passed as the `:format` option.
+- **Date** — `{d, date, short}` calls `I18n.localize` with `:format => :short`. The style maps directly to an I18n date format key. Common styles are `short`, `medium`, `long`, and `full`, but any key defined under `date.formats` in your locale file works.
+- **Time** — `{t, time, short}` works the same way, looking up keys under `time.formats`.
+
+For example, with these locale definitions:
+
+```yaml
+en:
+  date:
+    formats:
+      short: "%b %-d"
+      long: "%B %-d, %Y"
+  time:
+    formats:
+      short: "%H:%M"
+```
+
+The pattern `"Updated on {d, date, short}"` with `d: Date.new(2026, 1, 15)` produces `"Updated on Jan 15"`.
+
+### Plural Rules
+
+Plural rules are also delegated to the I18n backend. Any gem which supplies plural rules to I18n will work with `I18n::MessageFormat`, e.g. [`rails-i18n`](https://github.com/svenfuchs/rails-i18n).
+
+### Ordinal Rules
+
+Install built-in ordinal rules for selectordinal support:
+
+```ruby
+I18n::MessageFormat::OrdinalRules.install(:en)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Run tests with `bundle exec rake test`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/aergonaut/i18n-message_format. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/aergonaut/i18n-message_format/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/devenv.lock

@@ -0,0 +1,123 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1770744655,
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "d8bd7b74d0604227220074ac0bc934c4efb2b8fb",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1767039857,
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1770726378,
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "5eaaedde414f6eb1aea8b8525c466dc37bba95ae",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "git-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1762808025,
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "cb5e3fdca1de58ccbc3ef53de65bd372b48f567c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "inputs": {
+        "nixpkgs-src": "nixpkgs-src"
+      },
+      "locked": {
+        "lastModified": 1770434727,
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "8430f16a39c27bdeef236f1eeb56f0b51b33d348",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-src": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1769922788,
+        "narHash": "sha256-H3AfG4ObMDTkTJYkd8cz1/RbY9LatN5Mk4UF48VuSXc=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "207d15f1a6603226e1e223dc79ac29c7846da32e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "git-hooks": "git-hooks",
+        "nixpkgs": "nixpkgs",
+        "pre-commit-hooks": [
+          "git-hooks"
+        ]
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/devenv.nix

@@ -0,0 +1,57 @@
+{ pkgs, lib, config, inputs, ... }:
+
+{
+  # https://devenv.sh/basics/
+  env.GREET = "devenv";
+
+  # https://devenv.sh/packages/
+  packages = with pkgs; [
+    git
+    openssl
+    libyaml
+    postgresql
+    git
+    curl
+    redis
+    nixd
+    nixfmt-rfc-style
+  ];
+
+  # https://devenv.sh/languages/
+  # languages.rust.enable = true;
+
+  languages.ruby.enable = true;
+
+  # https://devenv.sh/processes/
+  # processes.cargo-watch.exec = "cargo-watch";
+
+  # https://devenv.sh/services/
+  # services.postgres.enable = true;
+
+  # https://devenv.sh/scripts/
+  scripts.hello.exec = ''
+    echo hello from $GREET
+  '';
+
+  enterShell = ''
+    hello
+    git --version
+  '';
+
+  # https://devenv.sh/tasks/
+  # tasks = {
+  #   "myproj:setup".exec = "mytool build";
+  #   "devenv:enterShell".after = [ "myproj:setup" ];
+  # };
+
+  # https://devenv.sh/tests/
+  enterTest = ''
+    echo "Running tests"
+    git --version | grep --color=auto "${pkgs.git.version}"
+  '';
+
+  # https://devenv.sh/git-hooks/
+  # git-hooks.hooks.shellcheck.enable = true;
+
+  # See full reference at https://devenv.sh/reference/options/
+}

data/devenv.yaml

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=https://devenv.sh/devenv.schema.json
+inputs:
+  nixpkgs:
+    url: github:cachix/devenv-nixpkgs/rolling
+
+# If you're using non-OSS software, you can set allowUnfree to true.
+# allowUnfree: true
+
+# If you're willing to use a package that's vulnerable
+# permittedInsecurePackages:
+#  - "openssl-1.1.1w"
+
+# If you have more than one devenv you can merge them
+#imports:
+# - ./backend

data/docs/plans/2026-02-25-icu-message-format-design.md

@@ -0,0 +1,141 @@
+# ICU Message Format for Ruby i18n — Design
+
+## Overview
+
+`i18n-message_format` is a Ruby gem that adds ICU Message Format support to the
+`i18n` gem. It provides a pure Ruby parser, a formatter integrated with existing
+i18n infrastructure, and a chainable backend for seamless use alongside standard
+translation files.
+
+## Architecture
+
+```
+YAML files --> Backend (load + lookup) --> Parser (string -> AST) --> Formatter (AST + args -> string)
+                                                   |
+                                             LRU Cache (pattern -> AST)
+```
+
+Three layers:
+
+1. **Parser** — recursive descent parser, string to AST
+2. **Formatter** — AST walker, resolves arguments to produce output
+3. **Backend** — `I18n::Backend::Base` implementation for use with `I18n::Backend::Chain`
+
+## Parser
+
+Pure Ruby recursive descent parser supporting the full ICU Message Format spec:
+
+- Literal text
+- Simple arguments: `{name}`
+- Formatted arguments: `{count, number}`, `{date, date, short}`
+- Plural: `{count, plural, one {# item} other {# items}}`
+- Select: `{gender, select, male {He} female {She} other {They}}`
+- Selectordinal: `{position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`
+- Nested messages (full recursive nesting)
+- Escaped braces: `'{` `'}` `''`
+
+### AST Node Types
+
+- `TextNode` — literal text
+- `ArgumentNode` — simple argument reference
+- `PluralNode` — plural selection
+- `SelectNode` — value-based selection
+- `SelectOrdinalNode` — ordinal plural selection
+- `NumberFormatNode` — number formatting
+- `DateFormatNode` — date formatting
+- `TimeFormatNode` — time formatting
+
+## Formatter
+
+Walks the AST and resolves each node:
+
+- **TextNode** — returns literal string
+- **ArgumentNode** — looks up named argument, calls `to_s`
+- **PluralNode** — uses i18n gem's plural rules (`i18n.plural.rule`) to pick the
+  correct branch. Handles exact matches (`=0`, `=1`). Replaces `#` with the
+  numeric value.
+- **SelectNode** — matches argument value against branches, falls back to `other`
+- **SelectOrdinalNode** — uses ordinal plural rules (`i18n.ordinal.rule`
+  convention, see below)
+- **NumberFormatNode** — formats via `I18n.l` / i18n number formatting
+- **DateFormatNode / TimeFormatNode** — formats via `I18n.l(value, format: style)`
+
+## Plural Rules
+
+### Cardinal (plural)
+
+Delegates to the i18n gem's existing pluralization infrastructure:
+
+- Looks up `i18n.plural.rule` in locale data (returns a lambda: count -> category)
+- Compatible with `rails-i18n` and other gems that ship pluralization rules
+- Falls back to English rules (1 = `:one`, else `:other`) when no rule is found
+
+### Ordinal (selectordinal)
+
+The i18n gem has no built-in ordinal convention. This gem defines one:
+
+- Convention: `i18n.ordinal.rule` in locale data (same lambda pattern)
+- Ships built-in ordinal rules for common locales (English, etc.)
+- Users or other gems can register additional ordinal rules
+
+## Backend
+
+`I18n::MessageFormat::Backend` implements `I18n::Backend::Base`.
+
+```ruby
+I18n.backend = I18n::Backend::Chain.new(
+  I18n::MessageFormat::Backend.new("config/locales/mf/*.yml"),
+  I18n::Backend::Simple.new
+)
+```
+
+- Loads translations from separate, configurable file paths (glob patterns)
+- All strings in those files are treated as Message Format patterns
+- On `translate`: parses the pattern (or fetches from cache), formats with arguments
+- Returns `nil` for missing keys so Chain falls through to the next backend
+- Uses standard i18n YAML structure (`en.some.key`)
+
+## LRU Cache
+
+- Keyed by raw pattern string
+- Default capacity: 1000 entries (configurable)
+- Thread-safe via `Mutex`
+- Stores parsed AST nodes
+
+## Public API
+
+```ruby
+# Standalone usage
+I18n::MessageFormat.format(
+  "{name} has {count, plural, one {# item} other {# items}}",
+  name: "Alice", count: 3
+)
+# => "Alice has 3 items"
+
+# Backend integration
+I18n.backend = I18n::Backend::Chain.new(
+  I18n::MessageFormat::Backend.new("config/locales/mf/*.yml"),
+  I18n::Backend::Simple.new
+)
+I18n.t("items.count", name: "Alice", count: 3)
+```
+
+## Error Handling
+
+- `I18n::MessageFormat::ParseError` — malformed patterns (includes line/column)
+- `I18n::MessageFormat::MissingArgumentError` — required argument not provided
+- Both inherit from `I18n::MessageFormat::Error`
+
+## Dependencies
+
+- **Runtime**: `i18n` gem only
+- **Development**: `minitest`, `rake`
+- **Ruby**: >= 3.2.0
+
+## Testing
+
+- Minitest
+- Parser tests covering all node types, nesting, edge cases, and error reporting
+- Formatter tests for each format type with multiple locales
+- Backend integration tests with Chain
+- Cache behavior tests