Localización
iVOLT no trae capa de traducción, ni archivos de idioma, ni diccionario en tiempo de ejecución. Escribe muy poco texto propio y casi todo es una opción que fijas en el HTML que ya sirves. Los números, las fechas y la ordenación salen de Intl, que lee el idioma del documento. Esta página enumera toda la superficie para que un traductor la vea de una vez.
Tres fuentes, en el orden en que las vas a tocar:
- El HTML servido. Etiquetas, títulos, opciones, pies y mensajes son tuyos; el paquete los mueve de sitio pero nunca los reescribe.
- Una opción
data-iv-*. Las pocas cadenas que genera el JavaScript — un estado vacío, una línea de estado, la etiqueta de un botón que crea — son valores por defecto que sobrescribes por elemento, o en JavaScript al inicializar. Intl. Nombres de mes y de día, la fecha completa que anuncia una celda, los números agrupados y la colación al ordenar una columna. El idioma es ellangdel elemento más cercano que lo declare, así que<html lang="es">suele ser toda la configuración.
Empieza por el idioma del documento
Fija lang y todo lo que depende de Intl le sigue. Una página en español no necesita ninguna opción para que las fechas se lean como fechas en español:
<html lang="es" class="iv-root" data-iv-theme="system">Una región en otro idioma lo declara en la región y los componentes de dentro lo recogen:
<section lang="en">
<input class="iv-input" type="date" data-iv-component="datepicker">
</section>Dos componentes admiten un idioma explícito cuando el visible y el de los datos no coinciden: data-iv-locale en la tabla de datos (para el colador que ordena) y en el selector de fecha (para el calendario).
Todas las cadenas generadas
La lista completa. Todo lo de esta tabla es una opción: ponla en el elemento como data-iv-<opción> o pásala a getOrCreate. Los marcadores entre llaves los sustituye el componente y deben sobrevivir a la traducción.
| Componente | Opción | Por defecto | Dónde se ve |
|---|---|---|---|
| Carousel | pauseText, playText, slideText, counterText | "Pause", "Play", "{index} of {total}", "{index} / {total}" | Etiqueta del botón de reproducción automática, que se alterna; el nombre accesible de cada diapositiva; el contador de posición visible, cuyos dígitos pasan por Intl.NumberFormat |
| Combobox | emptyText | "No matches" | La lista cuando nada coincide con lo escrito |
| Command | recentText, emptyText, placeholder | "Recent", "No results", "" | Título de los comandos recordados, estado vacío y marcador del campo |
| Counter | template, overText | "", "Too long" | El recuento bajo un campo ({count}, {max}, {remaining}) y lo que se anuncia al pasarse del límite |
| DataTable | emptyText, statusText, locale | "No rows match", "{visible} of {total} rows", el idioma del documento | Estado vacío y la región viva que se lee tras filtrar u ordenar |
| Datepicker | openText, dialogText, prevText, nextText, todayText, clearText, locale, firstDay | "Open calendar", "Choose a date", "Previous month", "Next month", "Today", "Clear" | El disparador, la etiqueta del calendario, sus dos botones de navegación y su pie. Los nombres de mes, las iniciales de los días y la fecha completa que anuncia cada día salen de Intl |
| Form | summaryTitle | "Please fix the following" | Título del resumen de errores. El mensaje de cada campo es el validationMessage del navegador, ya en el idioma del usuario, salvo que sirvas tu propio texto |
| Lightbox | closeText, prevText, nextText, zoomText, galleryLabel, counterText | "Close", "Previous", "Next", "Zoom", "Image viewer", "{index} / {total}" | Los cuatro botones del visor, el nombre accesible del diálogo y el contador de posición (dígitos por Intl.NumberFormat) |
| Picker | placeholder, searchPlaceholder, emptyText, countText, clearText, removeText | el <option> vacío o "Select…", "Search", "No matches", "{count} selected", "Clear selection", "Remove {label}" | El control cerrado, el campo de búsqueda, el estado vacío, el resumen de una selección múltiple y los nombres accesibles del botón de limpiar y del de quitar de cada ficha |
| Stepper | statusText | "Step {index} of {total}: {label}" | La región viva que se anuncia en cada cambio de paso |
| Toast | dismissText (en la región) | "Dismiss" | Nombre accesible del botón de cierre de cada aviso. El título y el mensaje salen de tu llamada a show() o del data-iv-message del disparador |
| Countup | grouping, decimals | true, -1 | Sin texto: la cifra se formatea con Intl.NumberFormat en el idioma del documento, así que una página en español cuenta pasando por 1.234,5 |
Un ejemplo en español por componente
Marcado real, tal como lo serviría una página en español. Aquí solo aparecen las cadenas generadas: el contenido visible ya se redacta en español.
<!-- Carrusel -->
<div class="iv-carousel" data-iv-component="carousel" data-iv-autoplay="5000"
data-iv-pause-text="Pausar" data-iv-play-text="Reproducir"
data-iv-slide-text="{index} de {total}" data-iv-counter-text="{index} de {total}">…</div>
<!-- Combobox -->
<div class="iv-combobox" data-iv-component="combobox" data-iv-empty-text="Sin coincidencias">…</div>
<!-- Paleta de comandos -->
<dialog class="iv-command" data-iv-component="command" data-iv-recent-text="Recientes"
data-iv-empty-text="Sin resultados" data-iv-placeholder="Escribe un comando…">…</dialog>
<!-- Contador -->
<textarea class="iv-textarea" data-iv-component="counter" data-iv-max="280"
data-iv-template="{remaining} caracteres restantes" data-iv-over-text="Demasiado largo"></textarea>
<!-- Tabla de datos -->
<table class="iv-table" data-iv-component="datatable" data-iv-locale="es"
data-iv-empty-text="Ninguna fila coincide"
data-iv-status-text="{visible} de {total} filas">…</table>
<!-- Selector de fecha -->
<input class="iv-input" type="date" data-iv-component="datepicker"
data-iv-open-text="Abrir el calendario" data-iv-dialog-text="Elige una fecha"
data-iv-prev-text="Mes anterior" data-iv-next-text="Mes siguiente"
data-iv-today-text="Hoy" data-iv-clear-text="Limpiar">
<!-- Formulario -->
<form class="iv-form" data-iv-component="form" data-iv-summary="true"
data-iv-summary-title="Corrige lo siguiente">…</form>
<!-- Visor de imágenes -->
<div class="iv-gallery" data-iv-component="lightbox" data-iv-gallery-label="Visor de imágenes"
data-iv-close-text="Cerrar" data-iv-prev-text="Anterior" data-iv-next-text="Siguiente"
data-iv-zoom-text="Ampliar" data-iv-counter-text="{index} de {total}">…</div>
<!-- Selector -->
<select class="iv-select" multiple data-iv-component="picker"
data-iv-search-placeholder="Buscar" data-iv-empty-text="Sin coincidencias"
data-iv-count-text="{count} seleccionados"
data-iv-clear-text="Limpiar la selección" data-iv-remove-text="Quitar {label}">
<option value="">Elige un país</option>
</select>
<!-- Región de avisos -->
<div class="iv-toast-region" id="avisos" data-iv-component="toast"
data-iv-dismiss-text="Descartar"></div>
<!-- Stepper -->
<div class="iv-stepper" data-iv-component="stepper"
data-iv-status-text="Paso {index} de {total}: {label}">…</div>Lo mismo en JavaScript, cuando el marcado lo produce un framework y las cadenas viven en tu propio catálogo:
import { Picker } from "@intervolutions/ivolt/picker";
Picker.getOrCreate(el, {
searchPlaceholder: t("buscar"),
emptyText: t("sinCoincidencias"),
countText: t("nSeleccionados"), // conserva el marcador {count}
});La precedencia es defaults < data-iv-* < opciones en JavaScript, así que un valor por defecto puesto en el marcado todavía puede sobrescribirse desde el catálogo al inicializar.
Marcadores, y qué no traducir
- Conserva las llaves.
{count},{visible},{total},{index},{label},{max}y{remaining}se sustituyen literalmente; una llave traducida se imprime como texto. - El orden de las palabras es libre. Cada marcador se sustituye allí donde aparezca, así que
"{visible} de {total} filas"vale igual que el orden inglés. - Los plurales son tuyos. El paquete no elige forma plural. Cuando una cadena tiene que servir para uno y para muchos, redáctala para que ambas lecturas funcionen, o fija la opción desde tu catálogo, que sí lo sabe.
- Los valores de opción no son texto.
placement,effect,filter,activationy los demás toman palabras clave fijas; traducirlas desactiva la opción.
De derecha a izquierda
Pon dir="rtl" en el documento o en una región. Las hojas están escritas con propiedades lógicas y los componentes con dirección — carrusel, cajón, marquesina, megamenú, popover, range y los efectos de brillo y exploración — se reflejan solos; no hay ninguna opción de por medio. Las flechas del teclado también siguen la dirección de escritura. Está probado en los tres motores.
Ya no queda nada fijado en el código
Hasta 0.9 seis cadenas las escribía el JavaScript sin opción detrás: el botón de cierre de un aviso, los de limpiar y quitar del selector, el nombre accesible de una diapositiva del carrusel y los dos contadores de posición. Ahora son opciones, así que una página puede traducirse de principio a fin sin tocar el marcado generado:
| Componente | Opción | Por defecto | En español |
|---|---|---|---|
| Toast (región) | dismissText | "Dismiss" | data-iv-dismiss-text="Descartar" |
| Picker | clearText | "Clear selection" | data-iv-clear-text="Limpiar la selección" |
| Picker | removeText | "Remove {label}" | data-iv-remove-text="Quitar {label}" |
| Carousel | slideText | "{index} of {total}" | data-iv-slide-text="{index} de {total}" |
| Carousel | counterText | "{index} / {total}" | data-iv-counter-text="{index} de {total}" |
| Lightbox | counterText | "{index} / {total}" | data-iv-counter-text="{index} de {total}" |
Los dos contadores formatean además sus dígitos con Intl.NumberFormat en el idioma del documento, así que un idioma con numerales propios los recibe sin más configuración. El glifo × del botón de descarte se queda como está: es decorativo, está oculto para la tecnología asistiva y lo que se anuncia es dismissText.
Cómo comprobar una traducción
- Abre la página con el idioma puesto y lee las regiones vivas con las herramientas de desarrollo, no solo el texto visible: el estado de la tabla de datos y el del stepper se anuncian, no se imprimen.
- Prueba el calendario con un idioma cuya semana empiece en lunes y con otro que empiece en domingo;
firstDayexiste para los entornos que no exponen la información de la semana. - Prueba una traducción larga en la maqueta estrecha: las etiquetas en español o en alemán suelen ser la mitad más largas que las inglesas, y los botones del visor y del carrusel van en fila.
- Comprueba que un número sigue leyéndose bien mientras el contador anima: el formato se elige una vez, a partir del idioma del documento.