@gringow/gringow-react 0.0.2 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# @gringow/gringow-react
|
|
2
|
+
|
|
3
|
+
React bindings for the Gringow AI powered translation engine. This package exposes a tiny React friendly wrapper on top of the core `@gringow/gringow` library so you can render translated template strings, consume cached translations, and switch languages at runtime.
|
|
4
|
+
|
|
5
|
+
## Highlights
|
|
6
|
+
- Declarative template strings via the `g` helper and a lightweight custom element
|
|
7
|
+
- Client side cache bootstrap through `GringowStore` with either a static JSON URL or a Gringow IO token
|
|
8
|
+
- Runtime language switching by dispatching the built in `LanguageChangeEvent`
|
|
9
|
+
- Ships typed exports (`.d.ts`) and tree shakeable modules ready for modern bundlers
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
```bash
|
|
13
|
+
pnpm add @gringow/gringow @gringow/gringow-react
|
|
14
|
+
# npm install @gringow/gringow @gringow/gringow-react
|
|
15
|
+
# yarn add @gringow/gringow @gringow/gringow-react
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### Peer requirements
|
|
19
|
+
- React 19 or newer
|
|
20
|
+
- A cache produced by the core Gringow tooling (CLI, Vite plugin, or direct API usage)
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
23
|
+
Configure the store once when your application boots and then render translated strings with the `g` helper.
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
// app-bootstrap.ts
|
|
27
|
+
import { GringowStore } from '@gringow/gringow-react'
|
|
28
|
+
|
|
29
|
+
GringowStore.defaultLanguage = 'en-US'
|
|
30
|
+
GringowStore.cacheUrl = '/gringow/gringow.json'
|
|
31
|
+
await GringowStore.fetchCache()
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
// Welcome.tsx
|
|
36
|
+
import { g } from '@gringow/gringow-react'
|
|
37
|
+
|
|
38
|
+
export function Welcome({ name }: { name: string }) {
|
|
39
|
+
return <>{g`Hello ${name}, welcome back!`}</>
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The helper flattens the template string, looks up the cached translation by ID, and renders a `<g-gringow>` custom element wrapped in `React.Suspense`. Until the cache is available the original template literal is used as a fallback.
|
|
44
|
+
|
|
45
|
+
## Managing the translation cache
|
|
46
|
+
The store can be fed from a static file or from the hosted Gringow IO endpoint.
|
|
47
|
+
|
|
48
|
+
```tsx
|
|
49
|
+
import { GringowStore } from '@gringow/gringow-react'
|
|
50
|
+
|
|
51
|
+
// Static JSON generated by the CLI or Vite plugin
|
|
52
|
+
GringowStore.cacheUrl = '/gringow/gringow.json'
|
|
53
|
+
|
|
54
|
+
// Or fetch from Gringow IO using a short lived token
|
|
55
|
+
GringowStore.gringowIoToken = process.env.GRINGOW_IO_TOKEN!
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Call `GringowStore.fetchCache()` to force a refresh whenever you invalidate the cache.
|
|
59
|
+
|
|
60
|
+
## Switching languages at runtime
|
|
61
|
+
Dispatch the `LanguageChangeEvent` from anywhere in your app. All mounted Gringow translations react to the global event.
|
|
62
|
+
|
|
63
|
+
```tsx
|
|
64
|
+
import { LanguageChangeEvent } from '@gringow/gringow-react'
|
|
65
|
+
|
|
66
|
+
function changeLanguage(lang: string) {
|
|
67
|
+
window.dispatchEvent(LanguageChangeEvent.create(lang))
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## API reference
|
|
72
|
+
- `g(strings, ...values)` returns a `React.ReactNode` bound to the Gringow cache
|
|
73
|
+
- `GringowStore` singleton exposes:
|
|
74
|
+
- `defaultLanguage` getter/setter
|
|
75
|
+
- `cacheUrl` and `gringowIoToken` setters (auto trigger cache fetch)
|
|
76
|
+
- `fetchCache(force?: boolean)` to load or refresh the cache
|
|
77
|
+
- `cache` getter with the resolved cache object (`Record<cacheId, GringowCacheItem>`)
|
|
78
|
+
- `LanguageChangeEvent` class with `EVENT_NAME` constant and `create(lang)` helper
|
|
79
|
+
|
|
80
|
+
## Development scripts
|
|
81
|
+
```bash
|
|
82
|
+
pnpm run build # Compile TypeScript to dist/
|
|
83
|
+
pnpm run watch # Rebuild on changes during local development
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## License
|
|
87
|
+
MIT © Renato Gaspar
|