Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ryohey/use-l10n
https://github.com/ryohey/use-l10n
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/ryohey/use-l10n
- Owner: ryohey
- License: mit
- Created: 2024-04-27T06:56:14.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-05-16T01:15:50.000Z (6 months ago)
- Last Synced: 2024-08-17T10:21:11.478Z (3 months ago)
- Language: TypeScript
- Size: 64.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# use-l10n: TypeScript Localization Library for React
`use-l10n` is a TypeScript library designed to provide an easy and type-safe way to implement localization in your React applications. By using a user-defined dictionary and custom hooks, this library allows for seamless integration of multiple languages, ensuring that keys are strongly typed and specific to your application.
[](https://badge.fury.io/js/use-l10n)
## Features
- **Type Safety**: Ensures that all localization keys are verified at compile time, reducing errors.
- **Customization**: Allows users to define their own localization components based on their unique dictionary.
- **Flexibility**: Supports dynamic language switching and can handle complex scenarios including browser settings and URL parameters.
## How it looks
### Hooks
```tsx
import { useLocalization } from "./l10n"
const App = () => {
const localized = useLocalization()
return (
{localized.hello}
{localized.description}
)
}
```
### Components
```tsx
import { Localized } from "./l10n"
const App = () => {
return (
)
}
```
## Installation
To get started with `use-l10n`, you can install the library via npm:
```bash
npm install use-l10n
```
Or using yarn:
```bash
yarn add use-l10n
```
## Setup
First, define your `localizationTable` with all supported languages and keys:
### `localizationTable.ts`
```typescript
export const localizationTable = {
en: {
hello: "Hello!",
"library-description":
"use-l10n is a library for easily implementing multilingual support in React applications.",
},
es: {
hello: "¡Hola!",
"library-description":
"use-l10n es una biblioteca para implementar fácilmente soporte multilingüe en aplicaciones React.",
},
fr: {
hello: "Bonjour!",
"library-description":
"use-l10n est une bibliothèque permettant de mettre en œuvre facilement le multilinguisme dans les applications React.",
},
de: {
hello: "Hallo!",
"library-description":
"use-l10n ist eine Bibliothek, um mehrsprachige Unterstützung in React-Anwendungen einfach zu implementieren.",
},
ja: {
hello: "こんにちは！",
"library-description":
"use-l10nは、Reactアプリケーションで簡単に多言語化を実現するためのライブラリです。",
},
"zh-Hans": {
hello: "你好",
"library-description":
"use-l10n是一个用于在React应用程序中轻松实现多语言化的库。",
},
"zh-Hant": {
hello: "你好",
"library-description":
"use-l10n是一個用於在React應用程序中輕鬆實現多語言化的庫。",
},
} as const
```
Next, create your localization context and hook using `createLocalization`:
### `useLocalization.ts`
```typescript
import { createLocalization } from "use-l10n"
export const { LocalizationContext, useLocalization, Localized } =
createLocalization(localizationTable, "en", [
[/^zh-Hans/, "zh-Hans"],
[/^zh-Hant/, "zh-Hant"],
[/^zh$/, "zh-Hans"],
[/^zh-TW$/, "zh-Hant"],
[/^zh-HK$/, "zh-Hant"],
[/^zh-MO$/, "zh-Hant"],
[/^zh-CN$/, "zh-Hans"],
[/^zh-SG$/, "zh-Hans"],
])
export type Language = keyof typeof localizationTable
export type LocalizationKey = keyof (typeof localizationTable)[Language]
```
### Setup your main application
Incorporate the `LocalizationContext.Provider` within your main application component. You can dynamically set the language based on user preferences, URL parameters, or browser settings.
### `App.tsx`
```tsx
import { LocalizationContext } from "./useLocalization"
render(
)
```
## Usage
## Dynamic Language Switching Example
This example demonstrates how you can allow users to switch the language dynamically within your application.
### `LanguageSwitcher.tsx`
```tsx
import React, { useState } from "react"
import { LocalizationContext } from "./useLocalization"
export const LanguageSwitcher = () => {
const [language, setLanguage] = useState("en") // Default language is English
const handleLanguageChange = (event) => {
setLanguage(event.target.value)
}
return (
Japanese
Simplified Chinese
Traditional Chinese
English
Spanish
French
German
)
}
```
## API Reference
### `createLocalization`
Creates a localization context and hook based on the provided dictionary.
```typescript
const { LocalizationContext, useLocalization, useCurrentLanguage, Localized } = createLocalization(
localizationTable: Record>,
defaultLanguage: string,
languageMappings: Array<[RegExp, string]>
)
```
### `LocalizationContext`
A React context that provides the current language to all child components.
### `useLocalization`
A custom hook for retrieving localized strings.
```typescript
const localized = useLocalization()
console.log(localized.hello) // "Hello!"
```
### `useCurrentLanguage`
A custom hook for retrieving the current language.
```typescript
const language = useCurrentLanguage()
console.log(language) // "en"
```
### `Localized`
A React component that renders the localized string based on the provided key.
```tsx
```