I18n
Ginjou can work with any i18n tool.
This layer gives Ginjou one shared i18n contract for translation and locale changes.
I18n Context
I18n context is the shared entry point for translation and locale state.
Interface
interface I18n {
translate: (key: string, params?: Record<any, any>) => string | undefined
getLocale?: () => string
setLocale?: (locale: string, options?: any) => void | Promise<void>
onChangeLocale?: (handler: (locale: string) => void) => () => void
}
Methods
| Method | What it does |
|---|---|
translate | Translate one key and optionally return undefined when a key is missing. |
getLocale | Read the current locale. |
setLocale | Change the current locale. |
onChangeLocale | Subscribe to locale changes and return a cleanup function. |
<script setup lang="ts">
import { defineI18nContext } from '@ginjou/vue'
import { createI18n } from '@ginjou/with-vue-i18n'
defineI18nContext(createI18n())
</script>
Translate
useTranslate() returns one translation function.
The function accepts a translation key, optional params, and an optional default value.
If there is no i18n context, or the key is missing, Ginjou falls back to the default value and then to the key itself.
<script setup lang="ts">
import { useTranslate } from '@ginjou/vue'
const t = useTranslate()
const title = t('posts.title')
const greeting = t('posts.greeting', {
name: 'Ada',
})
const emptyText = t('posts.empty', undefined, 'No posts yet')
</script>
<template>
<div>
<h1>{{ title }}</h1>
<p>{{ greeting }}</p>
<p>{{ emptyText }}</p>
</div>
</template>
<script lang="ts">
import { useTranslate } from '@ginjou/svelte'
const t = useTranslate()
const title = t('posts.title')
const greeting = t('posts.greeting', {
name: 'Ada',
})
const emptyText = t('posts.empty', undefined, 'No posts yet')
</script>
<div>
<h1>{title}</h1>
<p>{greeting}</p>
<p>{emptyText}</p>
</div>
This helper is the lowest-level translation entry point for your own components. It is also reused internally by many auth and data composables.
Locale
useLocale() reads and updates the current locale.
Reading uses getLocale(). Writing uses setLocale(). External locale changes stay in sync through onChangeLocale().
This helper only works when the context implements all three locale methods.
| Context method | Used for |
|---|---|
getLocale | Read the current locale when the ref is created. |
setLocale | Apply a locale change when the ref is written. |
onChangeLocale | Keep the ref in sync when locale changes outside the ref itself. |
<script setup lang="ts">
import { useLocale } from '@ginjou/vue'
const locale = useLocale()
</script>
<template>
<label>
Locale
<select v-model="locale">
<option value="en-US">en-US</option>
<option value="zh-TW">zh-TW</option>
</select>
</label>
<p>Current locale: {{ locale }}</p>
</template>
<script lang="ts">
import { useLocale } from '@ginjou/svelte'
const locale = useLocale()
</script>
<label>
Locale
<select bind:value={locale.value}>
<option value="en-US">en-US</option>
<option value="zh-TW">zh-TW</option>
</select>
</label>
<p>Current locale: {locale.value}</p>
If one of those locale methods is missing, useLocale() throws instead of trying to guess the behavior.
Official Adapter
The repo currently includes one official i18n adapter.