Introducción

La biblioteca generaltranslation es la biblioteca central de i18n de GT y reúne funciones y clases utilitarias para traducción y formateo. Se usa con mayor frecuencia junto con paquetes de framework como gt-next y gt-react, pero también puede utilizarse como biblioteca independiente.

import { GT } from 'generaltranslation';

const gt = new GT({
  apiKey: 'tu-apiKey',
  projectId: 'tu-projectId',
  sourceLocale: 'en',
  targetLocale: 'es',
});

// Traducir contenido
const result = await gt.translate('Hello, world!', 'es');
// "¡Hola, mundo!"
// "¡Hola, mundo!"

// Formatear números, fechas y divisas
const formattedPrice = gt.formatCurrency(29.99, 'USD');
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "9/25/2025"

// Trabajar con locales
const localeProps = gt.getLocaleProperties('fr-CA');
const isValid = gt.isValidLocale('de');
// { language: "fr", region: "CA", ... }
// true

Instalación

npm install generaltranslation

yarn add generaltranslation

bun add generaltranslation

pnpm add generaltranslation

Ejemplos

Existen dos tipos principales de traducción: traducción de cadenas y traducción de archivos.

Configuración

Para habilitar la traducción, debes proporcionar un id de proyecto y una clave de API. Consulta el método constructor para obtener más información.

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  targetLocale: 'es',
});

Traducción de cadenas

Consulta el método translate para obtener más información.

try {
  const result = await gt.translate('¡Hola, mundo!');
  console.log(result); // "¡Hola, mundo!"
} catch (error) {
  console.error('Error de traducción:', error.message);
}

Traducción de files

Los files se traducen como trabajos. Inicias un trabajo subiendo un file. Subir muchos files iniciará muchos trabajos.

Consulta los métodos uploadSourceFiles y checkFileTranslations para obtener más información.

// Archivos para cargar
const files = [
  {
    source: {
      fileName: 'src/components/Button.tsx',
      fileFormat: 'TSX',
      locale: 'en',
      content: '...',
    },
  },
];

// Cargar archivos fuente
await gt.uploadSourceFiles(files);

Tabla de contenido

GT Class

Clase principal para la traducción y el manejo de locale:

• Constructor - Inicializa una instancia de GT con una configuración
• setConfig - Actualiza la configuración de la instancia de GT

Métodos de traducción

• translate - Funcionalidad principal de traducción
• translateMany - Traducción por lotes
• setupProject - Inicialización del proyecto
• shouldSetupProject - Comprobar si es necesario configurar el proyecto
• checkSetupStatus - Verificar la configuración del proyecto
• getProjectData - Obtener información del proyecto
• uploadSourceFiles - Subir files para traducción
• enqueueFiles - Encolar files para su procesamiento
• checkFileTranslations - Comprobar el estado de las traducciones
• downloadTranslatedFile - Descargar un archivo traducido
• downloadFileBatch - Descargar varios archivos traducidos
• querySourceFile - Consultar información del archivo fuente

Métodos de formato

• formatMessage - Formato de texto internacionalizado
• formatNum - Formato de números
• formatDateTime - Formato de fecha y hora

Métodos de configuración regional

• getLocaleName - Obtener el nombre para mostrar de la configuración regional
• getLocaleProperties - Obtener información completa de la configuración regional
• getLocaleDirection - Obtener la dirección del texto de la configuración regional
• getLocaleEmoji - Obtener el emoji de bandera de la configuración regional
• getRegionProperties - Obtener información y propiedades de la región
• isValidLocale - Validar el código de configuración regional
• resolveAliasLocale - Convertir configuraciones regionales canónicas en alias
• resolveCanonicalLocale - Convertir configuraciones regionales alias a su forma canónica
• standardizeLocale - Estandarizar el formato del código de configuración regional
• isSameDialect - Comprobar si las configuraciones regionales representan el mismo dialecto
• isSameLanguage - Comprobar si las configuraciones regionales representan el mismo idioma
• isSupersetLocale - Comprobar relaciones jerárquicas entre configuraciones regionales
• determineLocale - Encontrar la mejor configuración regional según las preferencias
• requiresTranslation - Determinar si se requiere traducción

Funciones de utilidad

Funciones de formato

• formatMessage - Formateo de texto independiente
• formatNum - Formateo de números independiente
• formatDateTime - Formateo de fecha y hora independiente

Funciones de locale

• getLocaleName - Utilidad independiente para el nombre de la locale
• getLocaleProperties - Propiedades independientes de la locale
• getLocaleDirection - Utilidad independiente para la dirección del texto
• getLocaleEmoji - Utilidad independiente para el emoji
• getRegionProperties - Utilidad independiente para las propiedades de región
• isValidLocale - Validación independiente de la locale
• resolveAliasLocale - Resolución independiente de alias de locale
• standardizeLocale - Estandarización independiente de la locale
• isSameDialect - Comparación independiente de dialectos
• isSameLanguage - Comparación independiente de idiomas
• isSupersetLocale - Comprobación independiente de jerarquía de locale
• determineLocale - Negociación independiente de la locale
• requiresTranslation - Comprobación independiente de necesidad de traducción

Tipos e interfaces

Definiciones de TypeScript:

• GTConstructorParams - opciones de configuración
• LocaleProperties - información de locale completa
• TranslationResult - tipos de respuesta de traducción
• TranslateManyResult - respuesta de traducción por lotes
• FileToTranslate - configuración de traducción de archivos
• EnqueueFilesOptions - options de encolado de files
• Entry - estructura de Entry de traducción
• EntryMetadata - información de metadatos de Entry
• Content - definiciones de tipos de contenido
• Variable - estructura de Variable
• VariableType - definiciones de tipo de Variable
• JsxElement - tipo de elemento JSX
• JsxChild - tipo de hijo JSX
• JsxChildren - tipo de children de JSX
• DataFormat - especificaciones de DataFormat
• CustomMapping - configuración de CustomMapping

Próximos pasos

• Comienza con la GT class
• Explora los métodos de traducción
• Conoce las utilidades de locale
• Consulta las options de formato
• Explora las funciones independientes

Para el uso específico por framework, consulta la documentación de Next.js o React.