feat: New @wxt-dev/i18n package

[aklinker1]

Usage

# <srcDir>/locales/en.yml
simpleMessages: No need to use an object and provide a message or description field
chromeMessages:
  message: But you still can
  description: Same as the regular i18n setup, this field shouldn't be translated.
nested:
  messages: You can access nested messages using a "."
substitutions: You can include substitutions like $1
plurals:
  0: 0 items
  1: 1 item
  n: $1 items

You can use .json, .jsonc, .json5, .yaml, .yml, or .toml files for your messages

// Auto-imports from:
// import { i18n } from 'wxt/client';

i18n.t("simpleMessage")              // No need to use an object and provide a message or description field
i18n.t("chromeMessages")             // But you still can
i18n.t("nested.messages")            // You can access nested messages using a "."
i18n.t("substitutions", ["this!"])   // You can include substitutions like this!
i18n.t("plurals", 0)                 // 0 items
i18n.t("plurals", 1)                 // 1 item
i18n.t("plurals", 2)                 // 2 items
i18n.t("plurals", 2, ["Two"])        // Two items

Overview

This closes #327, newer version of PR #343. It's out of date, and now that the repo is a monorepo, it can be it's own package.

• Untyped client (i18n.t(...))
  • Plan for future pluralization resolvers (like arabic's few/many plural forms)

    -createI18n()
    +createI18n({ resolvePlurals: (forms, count, locale) => ... })

  • Plan for future substitution formatters (like money or numbers)

    -i18n.t("it-costs", [dollars])
    +i18n.t("it-costs", [i18n.money(dollars)])

• Allow customizing types (createI18n<MyI18n>(...))
• Detect number of substitutions and make it type-safe
• Generate declaration file for messages file
• Allow passing options into t(..., options)
• Utils for transforming custom JSON/JSON5/YAML to standard chrome extension json
  • Generate plurals in correct format
  • Support array keys
  • Use dots for nested objects/keys
  • Add @see links in JSDoc to link to original messages file? Not something all editors support, so skipping
• WXT Module
  • Generate and integrate types
  • Throw error if default_locale is missing
  • Regenerate and reload extension when saving localization file
• Check compatibility with i18n-ally VS code plugin
• Docs

This PR should cover all the feedback from:

• feat: Improved localization API #343 (comment)
• feat: Improved localization API #343 (comment)

Additional Info

I decided not to build this on top of i18next or a similar library and write it all from scratch. The reason is that the browser.i18n APIs are extremely basic and do not integrate with i18next:

1. i18next only supports being in-charge of loading the JSON files, support to "wrap" another library is non-existent. This means we would have to bundle and duplicate all the localization files across all the entrypoints. Edit: It is possible to load translations with a fetch call, without needing to "wrap" another library
2. Fallback languages are already handled by browser.i18n, and this conflicts with i18next's behavior. This would cause confusion.

So, no i18next. Build on top of browser.i18n with minimal overhead for features to improve DX.

[netlify]

✅ Deploy Preview for creative-fairy-df92c4 ready!

Name	Link
🔨 Latest commit	46de642
🔍 Latest deploy log	https://app.netlify.com/sites/creative-fairy-df92c4/deploys/66c3520443439f000817c5ae
😎 Deploy Preview	https://deploy-preview-758--creative-fairy-df92c4.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 82.02%. Comparing base (751706d) to head (46de642).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #758      +/-   ##
==========================================
+ Coverage   81.72%   82.02%   +0.30%     
==========================================
  Files         125      125              
  Lines        6592     6592              
  Branches     1092     1098       +6     
==========================================
+ Hits         5387     5407      +20     
+ Misses       1191     1171      -20     
  Partials       14       14              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[amal]

Amazing, can't wait to test it.

As for now, I've duplicated browser i18n with typesafe-i18n to provide users with the ability to select a language at runtime other than the browser default.

[aklinker1]

Yeah, that's one thing this won't be able to provide, choosing a different language at runtime. Limitation of the i18n APIs :/

[aklinker1]

Alright, here's working config for the VSCode i18n-ally extension:

# .vscode/i18n-ally-custom-framework.yml

# An array of strings which contain Language Ids defined by VS Code
# You can check available language ids here: https://code.visualstudio.com/docs/languages/identifiers
languageIds:
  - typescript

usageMatchRegex:
  - "[^\\w\\d]t\\(['\"`]({key})['\"`]"

# Disable other built-in i18n ally frameworks
monopoly: true

// .vscode/settings.json
{
  "i18n-ally.localesPaths": ["src/locales"],
  "i18n-ally.keystyle": "nested"
}

It works fine if you don't use the chrome format, and stick with simple text.

[aklinker1]

Alright, everything is implemented and tested, it's looking good!

I need to extract some changes to wxt into some other PRs, doing that now...