@agroshine/ags-web-i18n

Paquete centralizado de traducciones e internacionalización para las aplicaciones web de AgroShine.

Contiene todos los namespaces de ags-web-admin-front y ags-web-client-front en un solo lugar. Las apps dejan de mantener sus propios archivos de traducción y consumen este paquete.

Instalación

pnpm add @agroshine/ags-web-i18n

Peer dependencies requeridas (las apps ya las tienen):

pnpm add i18next react-i18next

Uso en las apps

1. Reemplazar la configuración de i18n

Elimina el contenido de src/i18n/ de cada app y deja un único archivo config.ts:

// src/i18n/config.ts
import { createI18nConfig } from '@agroshine/ags-web-i18n';

createI18nConfig();

El punto de entrada de la app sigue siendo el mismo:

// src/main.tsx
import '#i18n/config';

2. Usar traducciones en componentes

Nada cambia en el uso diario. Los namespaces y las keys son idénticos a los que ya existían:

import { useTranslation } from 'react-i18next';

// admin-front
function Sidebar() {
  const { t } = useTranslation('sidebar');
  return <span>{t('management')}</span>;
}

// client-front
function HealthPage() {
  const { t } = useTranslation('health');
  return <h1>{t('logbook.title')}</h1>;
}

// ambas apps
function LoginPage() {
  const { t } = useTranslation('login');
  return <button>{t('accept')}</button>;
}

3. Usar los tipos y utilidades de locale

import {
  type AppLocale,
  SUPPORTED_LOCALES,
  getBrowserLocale,
  getLocaleFromPathname,
  normalizeLocale,
} from '@agroshine/ags-web-i18n';

// Detectar idioma del navegador
const locale: AppLocale = getBrowserLocale(); // 'es' | 'en'

// Extraer idioma desde la URL
const lang = getLocaleFromPathname('/en/dashboard'); // 'en'

// Normalizar un string de idioma
const normalized = normalizeLocale('en-US'); // 'en'

// Lista de idiomas soportados
console.log(SUPPORTED_LOCALES); // ['es', 'en']

4. Acceder a los recursos crudos (opcional)

Si necesitas los objetos de traducción sin inicializar i18next:

import { sharedResources } from '@agroshine/ags-web-i18n';

console.log(sharedResources.es.login.title);
// → "Inicia sesión en nuestra plataforma"

API

createI18nConfig(opts?)

Inicializa i18next con todos los recursos del paquete y retorna la instancia configurada.

createI18nConfig(opts?: {
  lng?: string; // idioma inicial (por defecto: detecta el del navegador)
})

| Opción | Tipo | Por defecto | Descripción | |--------|------|-------------|-------------| | lng | string | getBrowserLocale() | Idioma inicial |

El fallback siempre es 'es'. Los idiomas soportados son ['es', 'en'].

getBrowserLocale(): AppLocale

Retorna el idioma del navegador normalizado. Si no está soportado, retorna 'es'.

normalizeLocale(value?): AppLocale | undefined

Normaliza un string de idioma (ej. 'en-US' → 'en'). Retorna undefined si no está en SUPPORTED_LOCALES.

getLocaleFromPathname(pathname): AppLocale | undefined

Extrae el idioma del primer segmento de una ruta URL (ej. '/en/dashboard' → 'en').

SUPPORTED_LOCALES

const SUPPORTED_LOCALES: readonly ['es', 'en']

AppLocale

type AppLocale = 'es' | 'en'

sharedResources

Objeto con todos los recursos de traducción agrupados por idioma y namespace. Útil para integraciones que necesitan los datos crudos sin instanciar i18next.

Namespaces disponibles

| Namespace | Origen | Descripción | |-----------|--------|-------------| | login | compartido | Pantalla de inicio de sesión | | forgotPassword | compartido | Recuperación de contraseña | | resetPassword | compartido | Restablecimiento de contraseña | | header | compartido | Cabecera y navegación superior | | sidebar | admin | Menú lateral del panel de administración | | breadcrumb | admin | Migas de pan | | groups | admin | Gestión de grupos | | customers | admin | Gestión de clientes y fincas | | crops | admin | Catálogo de cultivos | | users | admin | Gestión de usuarios | | indicators | admin | Indicadores de monitoreo | | varieties | admin | Variedades de cultivos | | permissions | admin | Permisos del sistema | | roles | admin | Roles del sistema | | nav | client | Navegación del cliente | | health | client | Módulo de sanidad | | estimates | client | Módulo de estimados | | sprinklers | client | Módulo de aspersiones | | postharvest | client | Módulo de poscosecha | | climate | client | Módulo de clima IoT | | config | client | Configuración del cliente |

Desarrollo

# Instalar dependencias
pnpm install

# Compilar el paquete
pnpm build

# Modo watch (desarrollo)
pnpm dev

# Verificar tipos
pnpm typecheck

# Formatear código
pnpm format

Agregar o modificar traducciones

Los archivos JSON están en src/locales/{es,en}/. Cada archivo corresponde a un namespace.

Después de editar, ejecuta pnpm build para regenerar el dist/.

Agregar un nuevo namespace

1. Crea los archivos src/locales/en/<namespace>.json y src/locales/es/<namespace>.json.
2. Impórtalos en src/locales/index.ts y agrégalos al objeto resources.
3. Ejecuta pnpm build.

Migración desde config local

Si la app tenía su propio src/i18n/, estos son los pasos para migrar:

1. Instalar el paquete: pnpm add @agroshine/ags-web-i18n
2. Eliminar src/i18n/locales/ (todos los JSON)
3. Eliminar src/i18n/locale.ts
4. Reemplazar src/i18n/config.ts con:

   import { createI18nConfig } from '@agroshine/ags-web-i18n';
   createI18nConfig();

5. Actualizar imports de tipos en la app:

   // antes
   import type { AppLocale } from '#i18n/locale';
   // después
   import type { AppLocale } from '@agroshine/ags-web-i18n';

Idiomas soportados

| Código | Idioma | |--------|--------| | es | Español (por defecto) | | en | Inglés |