Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

localize

/localize

Pisze zlokalizowane aplikacje w Elixirze z biblioteką Localize: formatowanie liczb, walut, dat, godzin, czasów trwania, jednostek, list, sortowanie i komunikaty MessageFormat 2, także przy migracji z ex_cldr.

Repozytorium
localize ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
7
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pisze zlokalizowane aplikacje w Elixirze z biblioteką Localize: formatowanie liczb, walut, dat, godzin, czasów trwania, jednostek, list, sortowanie i komunikaty MessageFormat 2, także przy migracji z ex_cldr.

Wyzwalacze z opisu

localize
Oryginalny opis (EN)

Write localized Elixir applications with the Localize library (hex package "localize") — formatting numbers, currencies, dates, times, durations, units of measure, lists, collation/sorting, and MessageFormat 2 messages. Use this skill whenever an Elixir app renders numbers, money, dates, times, quantities, or sorted text for people to read — even if the app targets a single locale — and for any task mentioning localize, ex_cldr migration, CLDR, locale validation, language tags, plural rules, or translatable message strings. Also use it when reviewing Elixir code that formats values by hand (in

Jak działa

  1. Why use it even for a single-locale app
  2. Core conventions (apply everywhere)
  3. Quick reference by subsystem
  4. Patterns for application code
  5. Common mistakes to catch in review
Sekcje z nagłówków SKILL.md, w oryginale · 143 linii, 1 178 słów
Podgląd SKILL.md
---
name: localize
description: Write localized Elixir applications with the Localize library (hex package "localize") — formatting numbers, currencies, dates, times, durations, units of measure, lists, collation/sorting, and MessageFormat 2 messages. Use this skill whenever an Elixir app renders numbers, money, dates, times, quantities, or sorted text for people to read — even if the app targets a single locale — and for any task mentioning localize, ex_cldr migration, CLDR, locale validation, language tags, plural rules, or translatable message strings. Also use it when reviewing Elixir code that formats values by hand (interpolation, Calendar.strftime, :io_lib.format, Enum.sort on user-visible strings) since Localize is usually the better replacement.
license: Apache-2.0
---

# Writing localized Elixir applications with Localize

Localize (hex: `localize`) formats numbers, currencies, dates/times, units, lists and messages using Unicode CLDR data, and sorts text with the Unicode Collation Algorithm. It is the successor to the `ex_cldr` family: one package, no compile-time backend modules, data loaded at runtime.

## Why use it even for a single-locale app

Hand-formatting is where localization bugs are born, and most of them bite in English too:

* `"#{count} files"` is wrong for `count == 1`. `Localize.Message.format/3` or a cardinal plural rule gets "1 file / 2 files" right for free.
* `"$#{amount}"` breaks on 1000000 (no grouping), negative amounts, and non-USD currencies. `Localize.Number.to_string(amount, format: :currency)` renders "$1,234.56" correctly today and "1.234,56 €" the day the app grows a second locale.
* `Calendar.strftime/3` hardcodes one ordering and one language of month names. `Localize.Date.to_string/2` gives the locale's convention.
* `Enum.sort/1` on user-visible strings puts "Zebra" before "apple" and mishandles accents. `Localize.Collation.sort/2` sorts the way people expect.

So when writing or reviewing Elixir that renders values for humans, reach for the Localize call rather than string interpolation, `strftime`, or raw `Enum.sort` — the single-locale output is equally correct and the app is localization-ready without a rewrite.

## Core conventions (apply everywhere)

* **Results are tagged tuples**: `{:ok, formatted}` or `{:error, %SomeError{}}` where the error is an exception struct with a readable `Exception.message/1`. Every formatter has a `!` variant that returns the bare value or raises.
* **Every formatting function takes a `:locale` option** defaulting to the process locale `Localize.get_locale()` (itself defaulting to the app config, then `:en`). Set it per-process with `Localize.put_locale/1`, per-call with `locale: "fr"`, or per-block with `Localize.with_locale/2`.
* **Validate untrusted locale input** with `Localize.validate_locale/1` — it parses, canonicalizes (aliases like `iw` → `he`), resolves likely subtags, applies `-u-` extensions, and caches. Pass the resulting `LanguageTag` around rather than re-validating strings.
* **Zero config is valid config.** With no configuration, `:en` works out of the box; other locales download on first use (integrity-verified). Configure `supported_locales` and `default_locale` when the app knows its audience.

```elixir
# config/config.exs — typical production setup
config :localize,
  default_locale: :en,
  supported_locales: [:en, :de, :fr, :ja],
  otp_app: :my_app
```

## Quick reference by subsystem

Each row shows the everyday call; the reference file has the full option set, more examples, and the edge cases. Read the reference file when the task goes beyond the row.

### Numbers, currencies, plurals — [references/numbers.md](references/numbers.md)

```elixir
Localize.Number.to_string(1234.5)                              # {:ok, "1,234.5"}
Localize.Number.to_string(1234.5, format: :currency)           # {:ok, "$1,234.50"} (currency from locale)
Localize.Number.to_string(1234.5, format: :currency, currency: :EUR, locale: :de)
                                                               # {:ok, "1.234,50 €"} (no-break space before €)
Localize.Number.to_string(0.456, format: :percent)             # {:ok, "46%"}
Localize.Number.to_string(1_234_000, format: :decimal_short)   # {:ok, "1.2M"}
Localize.Number.to_string(42, format: :ordinal)                # {:ok, "42nd"}
Localize.Number.PluralRule.plural_type(1, locale: :en)         # :one  (drive "file" vs "files")
Localize.Number.parse("1,234.56")                              # parse localized input back
```

Read the reference for: rounding and digit options, significant digits via patterns, spellout/RBNF, ranges ("3–5"), scanning numbers out of text, `Decimal` inputs, custom format patterns.

### Dates, times, intervals, durations — [references/dates-times.md](references/dates-times.md)

```elixir
Localize.Date.to_string(~D[2026-07-06])                        # {:ok, "Jul 6, 2026"}
Localize.Date.to_string(~D[2026-07-06], format: :full)         # {:ok, "Monday, July 6, 2026"}
Localize.DateTime.to_string(dt, format: :yMMMdHm)              # skeleton — locale picks the layout
Localize.Interval.to_string(~D[2026-07-06], ~D[2026-07-09])    # {:ok, "Jul 6 – 9, 2026"} (thin spaces around the dash)
Localize.DateTime.Relative.to_string(-3600)                    # {:ok, "1 hour ago"}
Localize.Duration.to_string(duration)                          # {:ok, "11 months and 30 days"}
```

Prefer style atoms (`:short`/`:medium`/`:long`/`:full`) or skeletons (`:yMd`, `:yMMMEd`, `:Hm`) over literal pattern strings — skeletons let each locale arrange fields its own way. Read the reference for: pattern symbols, time zones, week/quarter fields, non-Gregorian calendars, `to_time_string` clock-style durations.

### Units of measure — [references/units.md](references/units.md)

```elixir
unit = Localize.Unit.new!(3.5, "kilometer")
Localize.Unit.to_string(unit)                                  # {:ok, "3.5 kilometers"}
Localize.Unit.to_string(unit, format: :short)                  # {:ok, "3.5 km"}
Localize.Unit.convert(unit, "mile")                            # {:ok, mile-unit}
Localize.Unit.to_string(Localize.Unit.new!(5, "curr-usd-per-100-kilometer"))
                                                               # {:ok, "$5.00 per 100 kilometers"}
```

Compound identifiers compose (`kilowatt-hour`, `meter-per-second`, `foot-and-inch`); usage-based preferences (`usage: "person-height"`) pick regional units automatically. Read the reference for: conversion, mixed units, arithmetic, custom units, grammatical case/gender in inflected languages.

### Lists — inline, no reference needed

```elixir
Localize.List.to_string(["a", "b", "c"])                       # {:ok, "a, b, and c"}
Localize.List.to_string(["a", "b"], list_style: :or)           # {:ok, "a or b"}
```

Never `Enum.join(items, ", ")` user-facing lists — conjunction rules differ by locale and by list length.

### Collation (sorting and comparing text) — [references/collation.md](references/collation.md)

```elixir
Localize.Collation.sort(["banana", "Apple", "cherry"])          # ["Apple", "banana", "cherry"]
Localize.Collation.compare("résumé", "resume", strength: :primary)  # :eq — accent-insensitive
Localize.Collation.sort(["file10", "file2"], numeric: true)     # ["file2", "file10"]
Localize.Collation.sort_key("text")                             # store for DB-side ordering
```

Read the reference for: strength levels (accent/case-insensitive matching), `ignore_punctuation`, script reordering, locale collation types (`zh-u-co-pinyin`), search-style matching.

### MessageFormat 2 (translatable message strings) — [references/message-format.md](references/message-format.md)

```elixir
Localize.Message.format("{{Hello {$name}!}}", %{"name" => "World"})
# {:ok, "Hello World!"}

Localize.Message.format(
  ".input {$count :number}\n.match $count\n1 {{You have one file}}\n* {{You have {$count} files}}",
  %{"count" => 3}
)
# {:ok, "You have 3 files"}
```

MF2 is the right shape for any user-visible sentence containing a value: the plural/gender/select logic lives in the (translatable) message, not in Elixir `if`s. Read the reference for: built-in functions (`:number`, `:datetime`, `:currency`, `:unit`), markup, custom functions, Gettext integration, and when plain Gettext is the better fit.

### Locale validation, language tags, configuration — [references/locales-and-config.md](references/locales-and-config.md)

```elixir
{:ok, locale} = Localize.validate_locale("pt-br")     # canonical "pt-BR", ready to pass around
Localize.put_locale(locale)                           # set for this process
Localize.Territory.display_name(:NZ, locale: :fr)     # {:ok, "Nouvelle-Zélande"}
Localize.Currency.currency_from_locale(locale)        # territory-appropriate default currency
```

`-u-` extension keys on a locale (e.g. `"en-u-ca-buddhist-nu-thai-hc-h23"`) automatically drive calendar, digits, hour cycle, collation and more through every formatter. Read the reference for: the `LanguageTag` struct, supported/known vocabularies, display names, runtime data download and supervision, per-locale defaults derived from territory data.

## Patterns for application code

**Set the locale once per request, then format without ceremony.** In Phoenix, a plug resolves the user's locale (session, `Accept-Language`, URL) through `validate_locale/1` and calls `Localize.put_locale/1`; every downstream `to_string` call then does the right thing with no `:locale` plumbing.

**Prefer the non-bang variants at boundaries, bang variants internally.** User-supplied locales, currencies, or units can be invalid — handle `{:error, e}` (its `Exception.message/1` is presentable). For app-internal constants (`Localize.Unit.new!(1, "meter")`), the bang variant is cleaner and a raise means a programming error.

**Keep values as values until the last moment.** Store money as `Decimal` + currency code, dates as `Date`/`DateTime`, quantities as `Localize.Unit` — format at the presentation edge. Never parse formatted output back except with `Localize.Number.parse/2`.

**Plural-sensitive text belongs in messages, not conditionals.** Replace `if count == 1, do: "file", else: "files"` with an MF2 message or `PluralRule.pluralize/3` — English has 2 plural categories but Arabic has 6, and the conditional version silently caps the app at English.

## Common mistakes to catch in review

* String interpolation of numbers, money, dates, or lists into user-visible text.
* `Calendar.strftime/3` or `Timex.format` for user-facing dates (fine for logs and machine formats).
* `Enum.sort/1` / `Enum.sort_by(&String.downcase/1)` on human-visible lists.
* Hardcoded `"$"`, `"%"`, thousands separators, or month/day names.
* `String.to_atom(user_locale)` — use `validate_locale/1`, which is safe on untrusted input.
* Concatenating sentence fragments around a value ("You have " <> n <> " new") — word order varies; use MF2.
* Treating `validate_locale` output as a string — it returns a `%Localize.LanguageTag{}`; pass the struct.
Pliki w paczce (7)
  • SKILL.md 11 KB
  • references/collation.md 9 KB
  • references/dates-times.md 13 KB
  • references/locales-and-config.md 11 KB
  • references/message-format.md 11 KB
  • references/numbers.md 13 KB
  • references/units.md 11 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · elixir-localize/localize100MIT
optiflowic/keyturn100MIT
codegreenbaby/figma-comment-sync100MIT
aladicf/better-web-ui100MIT
imgly/codesign95MIT
ufortstephen/localize-dev90MIT
ghaida/intent90CC0-1.0

Migawka bazy z 13.11.2026 · wersja paczki cac9916ae28e (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100messageformat-net
    Pomaga korzystać z biblioteki MessageFormat.NET (Jeffijoe.MessageFormat) do formatowania komunikatów ICU: liczba mnoga, wzorce płci i select, złożone sparametryzowane komunikaty lokalizacyjne.
  • 100internationalization
    Przygotowuje aplikację do wielu języków i regionów: wydzielone teksty, formaty dat, liczb i walut, strefy czasowe oraz układ od prawej strony.
  • 100i18n-date-patterns
    Wdraża internacjonalizację w aplikacjach React: teksty interfejsu, obsługa dat i czasu, formatowanie zależne od lokalizacji, ICU MessageFormat oraz obsługa RTL.
  • 100locale-format-validator
    Weryfikuje, czy produkt poprawnie renderuje formaty zależne od ustawień regionalnych: daty, liczby, waluty, czasy i czasy trwania w konwencjach USA, Niemiec, Francji i Japonii.
  • 80Angular Localize v9 Migration
    Migruje aplikację Angular do narzędzi lokalizacji w wersji 9 i środowiska $localize, gdy i18n opiera się na starszej konfiguracji.
  • 90locale-aware-sorting
    Sortuje i porównuje tekst według reguł collation lokalizacji zamiast kolejności bajtów, aby listy czytały się poprawnie w każdym języku.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.