https://github.com/marcmartinezdev/fast-react-i18n
https://github.com/marcmartinezdev/fast-react-i18n
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/marcmartinezdev/fast-react-i18n
- Owner: MarcMartinezDev
- Created: 2025-07-15T08:34:41.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-15T09:04:02.000Z (11 months ago)
- Last Synced: 2025-07-15T19:14:45.096Z (11 months ago)
- Language: TypeScript
- Size: 21.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🌍 fast-react-i18n
Minimalist internationalization library for React with support for language detection, fallback, in-memory/localStorage caching, and dynamic loading of translations from JSON files.
---
## ✨ Characteristics
- ✅ Dynamic loading of translation files (/es.json, /en.json, etc.)
- 🌐 Automatic detection of the user’s language (?lang, cookies, browser)
- 💾 In-memory cache and optional persistence via localStorage
- 📉 Automatic fallback if the language is not found
- ⚡ Quick access hooks: useTranslation, useForceReloadTranslations, etc.
- 🧽 Cache clearing function: clearTranslationsCache
- 🌎 Loading available languages via locales.json
---
## 🚀 Instalation
```bash
npm install fast-react-i18n
```
## 📦 Expected translations structure
```bash
public/
└── locales/
├── en.json
├── es.json
└── locales.json ← ["en", "es"...]
```
## 🧩 Basic usage
1. Envolve your App
```bash
import { I18nProvider } from "fast-react-i18n";
```
2. Access translations
```bash
import { useTranslation } from "fast-react-i18n";
export const Home = () => {
const { translations } = useTranslation();
return
{translations.home?.title}
;
};
```
## 🛠 API
```bash
| Propiedad | Tipo | Descripción |
|---------------------|-----------|---------------------------------------------------------------------------|
| `initialLocale` | `string?` | Initial Lang (`"en"`, `"es"`... default `"auto"`) |
| `fallbackLocale` | `string?` | Alternative language if the primary one fails |
| `translationsPath` | `string` | Base path to your translation files (e.g., /locales) |
| `persist` | `boolean?`| Whether to save in localStorage (default: false) |
```
## Functions
### useForceReloadTranslations()
Manually reloads the current language.
### detectUserLocale()
Detects the user’s preferred language, in this order:
- Query param ?lang=
- Cookie lang=
- navigator.language
- "en" (by default)
### clearTranslationsCache()
Deletes from localStorage all translations stored under keys starting with i18n\_.
### loadAvailableLocales(path: string): Promise
Loads an array with the languages defined in locales.json.
## 💡 Best practices
Use nested objects for your translations ({ home: { title: "" } })
Control the language with setLocale if you need to change it manually
Clear the cache if translations change dynamically (e.g., from a CMS)
Use fallbackLocale to avoid errors if a file is missing