@intlayer/docs 5.7.7 → 5.8.0-canary.0

package/docs/de/packages/intlayer/index.md

@@ -149,8 +149,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",
@@ -175,8 +175,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",
@@ -201,8 +201,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",

package/docs/de/packages/next-intlayer/index.md

@@ -110,8 +110,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",
@@ -136,8 +136,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",
@@ -162,8 +162,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",

package/docs/de/packages/react-intlayer/index.md

@@ -110,8 +110,8 @@ const component1Content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",
@@ -136,8 +136,8 @@ const component1Content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",
@@ -162,8 +162,8 @@ const component1Content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Weniger als minus ein Auto",

package/docs/en/CI_CD.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-05-20
-updatedAt: 2025-06-29
+updatedAt: 2025-08-13
 title: CI/CD Integration
 description: Learn how to integrate Intlayer into your CI/CD pipeline for automated content management and deployment.
 keywords:
@@ -109,58 +109,82 @@ Intlayer provides a CLI command to autofill and review dictionary content. This
 
 ```yaml fileName=".github/workflows/intlayer-translate.yml"
 name: Intlayer Auto-Fill
+# Trigger conditions for this workflow
 on:
-  push:
-    branches: [ main ]
-    paths:
-      - 'src/**'
   pull_request:
-    branches: [ main ]
-    paths:
-      - 'src/**'
-  workflow_dispatch: {}
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+  pull-requests: write
 
 concurrency:
-  group: 'autofill-${{ github.ref }}'
+  group: "autofill-${{ github.ref }}"
   cancel-in-progress: true
 
 jobs:
   autofill:
     runs-on: ubuntu-latest
     env:
-      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
-      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      # OpenAI
+      AI_MODEL: openai
+      AI_PROVIDER: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
 
     steps:
+      # Step 1: Get the latest code from the repository
       - name: ⬇️ Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
-          persist-credentials: true
+          persist-credentials: true # Keep credentials for creating PRs
+          fetch-depth: 0 # Get full git history for diff analysis
 
+      # Step 2: Set up Node.js environment
       - name: 🟢 Set up Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 20 # Use Node.js 20 LTS for stability
 
+      # Step 3: Install project dependencies
       - name: 📦 Install dependencies
-        run: npm ci
+        run: npm install
+
+      # Step 4: Install Intlayer CLI globally for translation management
+      - name: 📦 Install Intlayer
+        run: npm install -g intlayer-cli
 
+      # Step 5: Build the Intlayer project to generate translation files
       - name: ⚙️ Build Intlayer project
         run: npx intlayer build
 
+      # Step 6: Use AI to automatically fill missing translations
       - name: 🤖 Auto-fill missing translations
-        run: npx intlayer fill --git-diff --mode fill
-
-      - name: 📤 Create or update translation PR
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: chore: auto-fill missing translations [skip ci]
-          branch: auto-translations
-          title: chore: update missing translations
-          labels: translation, automated
+        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+
+      # Step 7: Check if there are changes and commit them
+      - name: � Check for changes
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      # Step 8: Commit and push changes if any exist
+      - name: 📤 Commit and push changes
+        if: steps.check-changes.outputs.has-changes == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "chore: auto-fill missing translations [skip ci]"
+          git push origin HEAD:${{ github.head_ref }}
 ```
 
+To set up the environment variables, go to GitHub → Settings → Secrets and variables → Actions and add the secret .
+
 > Same as for Husky, in the case of a monorepo, you can use the `--base-dir` argument to sequentially treat each app.
 
 > By default, the `--git-diff` argument filters dictionaries that include changes from base (default `origin/main`) to current branch (default: `HEAD`).

package/docs/en/formatters.md

@@ -0,0 +1,250 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2025-08-20
+title: Formatters
+description: Locale-aware formatting utilities based on Intl for numbers, percentages, currency, dates, relative time, units, and compact notation. Includes a cached Intl helper.
+keywords:
+  - Formatters
+  - Intl
+  - Number
+  - Currency
+  - Percentage
+  - Date
+  - Relative Time
+  - Units
+  - Compact
+  - Internationalization
+slugs:
+  - doc
+  - formatters
+---
+
+# Intlayer Formatters
+
+## Overview
+
+Intlayer provides a set of lightweight helpers built on top of the native `Intl` APIs, plus a cached `Intl` wrapper to avoid repeatedly constructing heavy formatters. These utilities are fully locale-aware and can be used from the main `intlayer` package.
+
+### Import
+
+```ts
+import {
+  Intl,
+  number,
+  percentage,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+} from "intlayer";
+```
+
+If you are using React, hooks are also available; see `react-intlayer/format`.
+
+## Cached Intl
+
+The exported `Intl` is a thin, cached wrapper around the global `Intl`. It memoizes instances of `NumberFormat`, `DateTimeFormat`, `RelativeTimeFormat`, which avoids rebuilding the same formatter repeatedly.
+
+Because formatter construction is relatively expensive, this caching improves performance without changing behavior. The wrapper exposes the same API as the native `Intl`, so usage is identical.
+
+- Caching is per process and transparent to callers.
+
+> If `Intl.DisplayNames` is not available in the environment, a single dev-only warning is printed (consider a polyfill).
+
+Example:
+
+```ts
+import { Intl } from "intlayer";
+
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+```
+
+## Formatters
+
+All helpers below are exported from `intlayer`.
+
+### `number(value, options?)`
+
+Formats a numeric value using locale-aware grouping and decimals.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Examples:
+
+```ts
+import { number } from "intlayer";
+
+number(123456.789); // "123,456.789" (in en-US)
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+### `percentage(value, options?)`
+
+Formats a number as a percentage string.
+
+Behavior: values greater than 1 are interpreted as whole percentages and normalized (e.g., `25` → `25%`, `0.25` → `25%`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Examples:
+
+```ts
+import { percentage } from "intlayer";
+
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
+```
+
+### `currency(value, options?)`
+
+Formats a value as localized currency. Defaults to `USD` with two fraction digits.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Common fields: `currency` (e.g., `"EUR"`), `currencyDisplay` (`"symbol" | "code" | "name"`)
+
+Examples:
+
+```ts
+import { currency } from "intlayer";
+
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
+```
+
+### `date(date, optionsOrPreset?)`
+
+Formats a date/time value with `Intl.DateTimeFormat`.
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` or one of the presets:
+  - Presets: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+Examples:
+
+```ts
+import { date } from "intlayer";
+
+date(new Date(), "short"); // e.g., "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+### `relativeTime(from, to = new Date(), options?)`
+
+Formats relative time between two instants with `Intl.RelativeTimeFormat`.
+
+- Pass "now" as the first argument and the target as the second to get natural phrasing.
+- **from**: `Date | string | number`
+- **to**: `Date | string | number` (defaults to `new Date()`)
+- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
+  - Default `unit` is `"second"`.
+
+Examples:
+
+```ts
+import { relativeTime } from "intlayer";
+
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+```
+
+### `units(value, options?)`
+
+Formats a numeric value as a localized unit string using `Intl.NumberFormat` with `style: 'unit'`.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Common fields: `unit` (e.g., `"kilometer"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
+  - Defaults: `unit: 'day'`, `unitDisplay: 'short'`, `useGrouping: false`
+
+Examples:
+
+```ts
+import { units } from "intlayer";
+
+units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (locale-dependent)
+```
+
+### `compact(value, options?)`
+
+Formats a number using compact notation (e.g., `1.2K`, `1M`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }` (uses `notation: 'compact'` under the hood)
+
+Examples:
+
+```ts
+import { compact } from "intlayer";
+
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
+```
+
+## Notes
+
+- All helpers accept `string` inputs; they are internally coerced to numbers or dates.
+- Locale defaults to your configured `internationalization.defaultLocale` if not provided.
+- These utilities are thin wrappers; for advanced formatting, pass through the standard `Intl` options.
+
+## Entry points and re-exports (`@index.ts`)
+
+The formatters live in the core package and are re-exported from higher-level packages to keep imports ergonomic across runtimes:
+
+Examples:
+
+```ts
+// App code (recommended)
+import { number, currency, date, Intl } from "intlayer";
+```
+
+### React
+
+Client components:
+
+```ts
+import { useNumber, useCurrency, useDate } from "react-intlayer/format";
+// or in Next.js apps
+import { useNumber, useCurrency, useDate } from "next-intlayer/client/format";
+```
+
+Server components (or React Server runtime):
+
+```ts
+import { useNumber, useCurrency, useDate } from "react-intlayer/server/format";
+// or in Next.js apps
+import { useNumber, useCurrency, useDate } from "next-intlayer/server/format";
+```
+
+> That hooks will consider the locale from the `IntlayerProvider` or `IntlayerServerProvider`
+
+### Vue
+
+Client components:
+
+```ts
+import { useNumber, useCurrency, useDate } from "vue-intlayer/format";
+```
+
+> That composables will consider the locale from the injected `IntlayerProvider`
+
+## Doc History
+
+| Version | Date       | Changes                      |
+| ------- | ---------- | ---------------------------- |
+| 5.8.0   | 2025-08-20 | Add vue formatters           |
+| 5.8.0   | 2025-08-18 | Add formatters documentation |