Saltar al contenido
SheetForge

Hojas de localización

Una sola hoja contiene el texto de tu juego en todos los idiomas: las filas son claves, las columnas son configuraciones regionales. Una hoja de localización es una hoja de SheetForge ordinaria en todo lo que importa — se importa, se valida, se exporta, se envía con Push y hace round-trip exactamente igual que una hoja de datos — y cuando el paquete Unity Localization (com.unity.localization) está instalado, cada importación completada también rellena las propias colecciones StringTable del paquete a partir de ella. Tu runtime consume entonces referencias LocalizedString estándar mientras la hoja sigue siendo la única fuente de verdad.

Esta página trata sobre el texto de tu juego. La interfaz en 10 idiomas del propio producto es un tema aparte — consulta Localización.

La forma de la hoja (@loc)

Una hoja se convierte en una hoja de localización al llevar una fila de marcador @loc. Como @overlap y @style, puede ir en cualquier lugar por encima de los datos; su celda en cada columna nombra el código de configuración regional de esa columna:

@loc     |            | en             | ko          |       |
@name    | codeName   | en             | ko          | smart | comment
@type    | RecordId   | string?        | string?     | bool? | string?
@desc    | key        | source text    | Korean      |       |
         | ui.ok      | OK             | 확인        | false | Confirm button
         | ui.cancel  | Cancel         | 취소        |       |
  • La columna clave RecordId es obligatoria — el valor de clave de cada fila (ui.ok) es la clave de localización, y el nombre de la pestaña es el nombre de la colección StringTable: una pestaña = una colección.
  • Una columna de configuración regional es una columna de tipo string cuya celda @loc lleva el código (en, ko, pt-BR — cualquier etiqueta con forma de identificador; SheetForge valida la forma de la ortografía, no la existencia del código, y dos columnas cuyos códigos difieran solo en mayúsculas/minúsculas se rechazan). Escríbelas como string?: una celda sin traducir es entonces una brecha de cobertura, no un error de importación — consulta Cobertura más abajo.
  • La primera columna de configuración regional es la de origen. Su texto es lo que la celda de referencia de una hoja de datos previsualiza en línea, y lo que escribe la generación automática de claves.
  • Dos columnas opcionales reservadas, identificadas por nombre: smart (un booleano — marca la entrada como Smart String de Unity Localization) y comment (un string — sincronizado en los metadatos de comentario de la entrada). Cuando están presentes, la hoja es la verdad para esos datos; cuando están ausentes, el puente deja intactos los metadatos de tabla correspondientes. Una columna reservada no puede llevar también un código de configuración regional.
  • Se requiere al menos un código de configuración regional, y una hoja no puede ser a la vez una hoja de enum y una hoja de localización (@enum + @loc es un error de conflicto, reportado una vez).

Todo lo demás es una hoja ordinaria: la preparación y Ctrl+Z, la edición de estructura, la agrupación @style, los ciclos de ida y vuelta con xlsx y Google, Push, y la app web tratan todo esto como una tabla normal. Lo que cambia es la salida: una pestaña de localización no emite clase de registro generada, ni ScriptableObject de base de datos, ni dirección de Addressables. En su lugar, alimenta dos cosas — las constantes de clave y el puente.

Referenciar texto desde hojas de datos (LocRef@Tab)

Una hoja de datos apunta a una entrada de localización con una columna de referencia LocRef:

@name    | codeName    | displayName
@type    | RecordId    | LocRef@Strings
@desc    | unique key  | shown in UI
         | item.sword  | item.sword.name

LocRef@Strings se comporta exactamente igual que las referencias integradas que ya conoces (RecordId@Tab):

  • Validada por integridad en el import — una clave que no existe en la pestaña Strings es un error estructurado con una sugerencia de coincidencia más cercana; un error tipográfico muere en el import, no en tiempo de ejecución. El destino debe ser una hoja de localización (LocRefTargetNotLocalizationSheet en caso contrario), y un LocRef sin @Target se rechaza sugiriendo la escritura correcta.
  • Rieles de referencia completos — el selector de claves con búsqueda, la propagación de renombrado de clave (renombrar una clave reescribe cada celda que la referencia en el mismo lote), las aristas de grafo en el lienzo de registros, las reglas de lista desplegable exportadas, y la detección de huérfanos funcionan todos, tanto en el editor como en la app web.
  • Se compone como cualquier referencia — List<LocRef@Strings> y la forma opcional LocRef@Strings? (una celda vacía es una referencia vacía) funcionan ambas.
  • La celda muestra el texto, no solo la clave. Una celda LocRef previsualiza en línea el texto de la configuración regional de origen de la entrada, así que una hoja llena de claves se sigue leyendo como frases. El lienzo de registros hace lo mismo: las filas de referencia llevan el texto de origen en línea, y un valor truncado siempre conserva su texto completo en la descripción emergente.
  • Escribir en una celda vacía genera la entrada. Escribe el texto de origen en una celda LocRef vacía y SheetForge prepara, como un solo gesto y un solo paso de deshacer: una clave nueva en la hoja de localización destino (sugerida a partir de los nombres del registro y del campo — renómbrala libremente después, la propagación mantiene intacta cada referencia), el texto que escribiste como su valor en la configuración regional de origen, y la referencia en la celda en la que escribiste. Ambos hosts.

Qué llega a tu código

El codegen emite el campo como LocRef — una struct serializable sencilla (la tabla destino y la clave) que vive en el ensamblado de runtime de SheetForge y compila tanto si el paquete Unity Localization está instalado como si no; el código generado y los ScriptableObjects generados mediante bake nunca contienen un tipo del paquete. Con el paquete instalado, una llamada de extensión lo conecta con él:

var text = definition.displayName.ToLocalizedString(); // UnityEngine.Localization.LocalizedString

ToLocalizedString() solo existe cuando el paquete está presente (un version-define, SHEETFORGE_LOCALIZATION, activa la capa de extensión — el mismo mecanismo que usa SHEETFORGE_ADDRESSABLES). Sin el paquete, el campo sigue siendo un par tabla/clave bien formado que puedes consumir tú mismo.

Qué genera una importación

Junto con las salidas habituales, una importación escribe un único SheetForgeLocalizationKeys.cs para todo el proyecto — una clase estática por pestaña de localización (StringsKeys, …) que contiene un public const string por clave, de modo que el código de juego puede escribir StringsKeys.ui_ok en lugar de un "ui.ok" desnudo, y obtener seguridad en tiempo de compilación además de autocompletado del IDE.

  • Los nombres de miembro son las claves saneadas a identificadores de C# (los caracteres fuera de las letras ASCII, los dígitos y _ se convierten en _; las colisiones reciben un sufijo numérico determinista). Mantén las claves en ASCII si quieres constantes utilizables — una clave totalmente no ASCII se sanea en una sopa de guiones bajos.
  • Igual que el archivo de enum definido en hoja, el archivo de constantes es una salida a nivel de proyecto y siempre termina en la carpeta de código generado de los ajustes — se aplica la misma nota de ensamblado en Capacidades y límites.
  • Una pestaña de localización sin filas mantiene una clase vacía, así que vaciar una hoja no rompe el código que hace referencia al tipo.

El puente de Unity Localization

Con el paquete instalado, SheetForge mantiene una colección StringTable por pestaña de localización — claves, valores, y los datos smart/comment cuando esas columnas existen.

  • Cuándo se ejecuta: automáticamente, en el momento en que una importación se completa — la misma posición permanente que tienen Export y Push como salidas — más una acción manual de resincronización para ejecutarlo bajo demanda.
  • Dirección: en un solo sentido, hoja → tablas. La hoja es canónica; las tablas son la salida.
  • Configuraciones regionales: una configuración regional de la hoja sin un asset Locale coincidente en el proyecto se crea automáticamente y se nombra en el informe. Una configuración regional que solo existe en el proyecto se deja intacta y se reporta como no cubierta por la hoja.
  • Los renombrados de clave mantienen vivas las referencias de escena. Renombrar una clave en el Data Studio pasa por la misma maquinaria de renombrado que usa cualquier referencia, y el puente renombra la entrada de tabla in situ, preservando su id interno — un LocalizedString en una escena o prefab se enlaza a ese id, así que sobrevive al renombrado. El límite honesto: un renombrado hecho fuera del Studio — editando la fuente de la hoja directamente en Google Sheets o Excel — es indistinguible de eliminar una clave y añadir otra. El puente creará una entrada nueva (id nuevo) y tratará la antigua como huérfana; las referencias de escena a la entrada antigua siguen apuntando a la huérfana. Renombra las claves en el Studio.
  • Los metadatos que la hoja no modela siempre se preservan. Los comentarios (cuando no hay columna comment), los indicadores de exclusión, y cualquier otro metadato de tabla pasan intactos por cada sincronización.

Las ediciones externas se preguntan, nunca se fusionan en silencio

El puente estampa las tablas que posee y recuerda una huella de la última sincronización. Si una tabla cambió desde entonces — alguien la editó en la ventana Localization Tables, o se volcó contenido en ella con la propia extensión de Google Sheets de Unity — la siguiente sincronización se detiene y pregunta: sobrescribir desde la hoja, o abortar con un informe de diferencias. No hay fusión silenciosa ni sobrescritura silenciosa. Si quieres un flujo de trabajo de dos cabinas, encamina la otra cabina a través de la hoja en su lugar — para eso existe la exportación de traducción.

Las claves huérfanas se preservan por defecto

Una clave que existe en la tabla pero ya no en la hoja es una huérfana: se mantiene, se lista en un informe de huérfanas, y se puede eliminar mediante una acción de limpieza explícita (todas a la vez o una por una). Un interruptor de ajustes cambia a eliminar al sincronizar si quieres que la tabla refleje la hoja exactamente. Nada se destruye nunca como efecto secundario.

Sin el paquete

El paquete Unity Localization es opcional. Sin él:

  • Las hojas de localización son hojas completas — la creación, la validación, la cobertura, Export, Push, xlsx, la app web, las constantes de clave y los campos LocRef funcionan por completo.
  • Lo único que espera es la salida de sincronización de StringTable, que muestra un aviso de instalación (una vez por sesión) y se detiene — el mismo patrón de orientación que Addressables, e igualmente nunca instalado de forma programática.
  • Todos los ensamblados y todas las líneas de código generado compilan sin el paquete. Versión de paquete compatible: 1.5 o más reciente.

Migrar tablas existentes a una hoja

¿Ya usas Unity Localization? Un importador inverso convierte una colección StringTable existente en una hoja de localización, escrita directamente en tu origen de importación e importada automáticamente — el mismo camino que toma la creación de hojas. Revísala y edítala después como cualquier otra hoja. Si no se puede escribir en el origen activo desde el editor, el archivo aterriza junto a tu salida de Export con una nota que te pide moverlo. Cuando el puente después sincroniza esa hoja de vuelta a la misma colección, los ids de entrada se heredan por coincidencia de nombre de clave — las referencias LocalizedString existentes en escenas y prefabs sobreviven a la migración sin romperse.

Flujos de trabajo de traducción

Cobertura: las celdas sin traducir se reportan, no se rechazan

Una celda de configuración regional vacía no es un error — la importación reporta la cobertura por configuración regional (cuántas claves ha traducido cada configuración regional, y cuáles faltan), y todas las salidas permanecen abiertas. El texto llega de forma incremental; la hoja nunca se bloquea por una traducción sin terminar.

La lente de configuración regional

¿Trabajando en un idioma a la vez? Una lente de configuración regional alterna qué columnas de configuración regional son visibles. Es un metadato de visualización de la familia @style — nunca toca la huella de importación, el codegen, ni ninguna salida. Ambos hosts.

Exportación de traducción y reimportación parcial

Para entregar un idioma a un traductor, exporta un libro de traducción: elige las configuraciones regionales y obtén un xlsx de clave + texto de origen + comentario + una columna de estado, donde una entrada cuyo texto de origen cambió desde la última exportación se marca como desactualizada. Cuando el archivo vuelve, reimpórtalo como una fusión parcial: las filas se emparejan por clave y solo se escriben las columnas de configuración regional — la estructura, las otras configuraciones regionales y todo lo demás en la hoja permanecen intactos. Ambos hosts. Una asimetría honesta: la memoria de estado vive en un archivo local de la máquina junto al proyecto de Unity, así que un libro exportado desde el navegador siempre dice new en su columna de estado; el aviso de «traducido contra un texto de origen anterior» al reimportar compara con el texto de origen que el propio archivo lleva, de modo que funciona en ambos hosts.

XLIFF y pseudolocalizaciones

SheetForge deliberadamente no reimplementa XLIFF ni la pseudolocalización — las tablas que rellena el puente son tablas ordinarias de Unity Localization, así que las propias herramientas de exportación/importación XLIFF y pseudolocalización del paquete funcionan sobre ellas como en cualquier proyecto. Recuerda, eso sí, la autoridad de un solo sentido: la salida que esas herramientas escriben en las tablas cuenta como una edición externa que la siguiente sincronización preguntará. Para mantener las traducciones en la única fuente de verdad, tráelas de vuelta a través de la hoja (el libro de traducción de arriba) en lugar de hacia las tablas.

Dos límites relacionados, dichos con honestidad: el puente cubre solo tablas de string — las tablas de assets son un elemento reconocido del backlog — y SheetForge no distribuye ayudantes de Smart Format específicos de idioma (la selección de partículas gramaticales del coreano, por ejemplo). La columna smart marca las entradas como Smart Strings; los formateadores más allá de lo que ofrece el paquete son cosa tuya, a través de los propios puntos de extensión del paquete.

En la app web

Una hoja de localización es una hoja ordinaria en el navegador: la creación, la validación, la cobertura, el selector LocRef con texto de origen en línea, la generación de claves, la lente de configuración regional, y el libro de traducción funcionan todos en web.sheetforge.workers.dev. La sincronización de StringTable es trabajo del editor de Unity — el navegador no tiene un proyecto de Unity donde escribir las tablas, y no pretende tenerlo.

Páginas relacionadas