¿Qué partes se pueden traducir durante la localización JSON y qué partes no se deben cambiar?

Un fallo común en la localización JSON es: los botones de la página se han cambiado a inglés, pero el programa no puede encontrar los elementos de configuración correspondientes. La razón suele ser que cada cadena del objeto se entrega al traductor para su procesamiento, y el nombre de la clave, el enrutamiento y la codificación comercial también cambian en consecuencia. Este artículo está escrito para desarrolladores y personal de localización responsable de la configuración internacional. Explica cómo delinear primero los caminos de campo traducibles y luego realizar la aceptación.

Los ejemplos utilizan muestras sintéticas para demostrar los métodos de procesamiento y el código se ha verificado en un entorno aislado, pero esto no representa una garantía de todos los archivos reales o del rendimiento del producto. Antes de procesar documentos importantes, conserve los originales y revíselos de acuerdo con los límites y elementos de aceptación del texto.

¿Qué se puede traducir durante la localización JSON? Conclusión de una frase

Sólo se traducirán las rutas de redacción indicadas anteriormente. Los nombres clave, los valores de ruta y los códigos comerciales seguirán siendo los mismos, y se utilizará una lista de verificación de aceptación para confirmar que las piezas no modificadas efectivamente no se han modificado.

Comience con la ruta del campo en lugar de atravesar todas las cadenas

Tratar buttons.save como una dirección es más confiable que reemplazar la cadena "guardar" cuando la vea. La misma oración puede aparecer en la copia de la interfaz, las muestras de registros y los casos de prueba al mismo tiempo, y es posible que no sea necesaria la traducción en los tres lugares.

Las rutas deben representarse sin ambigüedades mediante tuplas o punteros JSON. Al simplemente empalmar con puntos, se producirá ambigüedad si el nombre de la clave contiene puntos.

El siguiente ejemplo solo limita dos rutas específicas y deja el resto del contenido como está. Esta es una estrategia de localización para este artículo, no un requisito del formato JSON en sí. La muestra sintética contiene texto de interfaz y un valor de ruta que no se debe cambiar para facilitar la verificación de límites.

Cambiar solo los valores permitidos explícitamente a la vez

import copy

source = {"buttons": {"save": "保存", "cancel": "取消"},
          "route": "/settings", "version": 1}
approved = {("buttons", "save"): "Save",
            ("buttons", "cancel"): "Cancel"}

def apply_texts(document, replacements):
    result = copy.deepcopy(document)
    for path, translated in replacements.items():
        if not path or not isinstance(translated, str):
            raise ValueError("invalid replacement")
        parent = result
        for key in path[:-1]:
            parent = parent[key]
        key = path[-1]
        if key not in parent or not isinstance(parent[key], str):
            raise ValueError("target must be an existing string")
        parent[key] = translated
    return result

result = apply_texts(source, approved)
assert result["buttons"]["save"] == "Save"
assert result["route"] == source["route"]
assert source["buttons"]["save"] == "保存"
try:
    apply_texts(source, {("version",): "one"})
except ValueError:
    pass
else:
    raise AssertionError("numeric field must be rejected")

El ejemplo solo demuestra el nivel de objeto, no implementa la indexación de matrices y no llama al servicio de traducción. Al enviar al canal real, la lista de rutas permitidas debe determinarse antes de la traducción, y no se puede permitir que la parte que genera la traducción amplíe el alcance de sus propias modificaciones al mismo tiempo.

La copia profunda puede evitar que los objetos de entrada se modifiquen en su lugar, pero no es un sistema de transacciones. La persistencia aún debe diseñarse por separado.

La aceptación depende de las partes sin cambios.

No basta con verificar que "el idioma de destino esté presente". También se debe guardar una lista de rutas y hashes del archivo fuente. Si la ruta se elimina después de actualizar el archivo fuente, la traducción anterior no se puede volver a escribir automáticamente con nombres de campos similares.

Las matrices, los valores nulos y las claves duplicadas deben considerarse por separado

• Matriz: después de reorganizar los elementos, es posible que el índice aún no apunte a la copia original. Cuando hay una ID estable, la ID se utiliza primero para el mapeo.
• Nulo: null no es una cadena vacía y no debe reemplazarse con el literal "vacío" para facilitar la traducción.
• Clave duplicada: es posible que la información de la clave duplicada se haya perdido después de completar el análisis JSON normal. Si desea rechazar claves duplicadas, debe manejarlas durante la etapa de análisis en lugar de esperar a que finalice la traducción. Referencia Documentación JSON de Python.

Este ejemplo es adecuado para una localización de configuración bien estructurada, no para un traductor automático JSON arbitrario. Al aceptar la traducción, primero confirme que la estructura y los campos protegidos no hayan cambiado y luego analice si el idioma es natural. La secuencia de solución de problemas será más clara.

📊 Comparación central

🎯 ¿Qué método es el adecuado para ti?

si usted……

• Para mantener el archivo de configuración de la interfaz, si desea que la copia del botón sea traducible y que la configuración del programa permanezca sin cambios, utilice la lista blanca de rutas de campo y determine la lista de rutas antes de la traducción.
• Los elementos de la matriz se pueden reorganizar; dé prioridad al uso de ID estables para el mapeo en lugar de depender de índices.
• El archivo fuente se actualizará continuamente. Guarde el hash del archivo fuente y la lista de rutas. Si la ruta desaparece, se producirá un error y la traducción anterior no se reescribirá automáticamente.
• Si necesita tramitar la entrega de documentos reales, por favor haga una lista de revisión de las rutas permitidas, texto original y traducción, y revíselos uno por uno.

❓ Preguntas frecuentes (FAQ)

1. ¿Por qué no traducir directamente todas las cadenas en JSON?

Porque la misma cadena puede ser una copia de la interfaz, el nombre de la clave del programa o el código comercial al mismo tiempo. Cuando cada cadena se entrega al traductor, el nombre de la clave, el enrutamiento y la codificación comercial también pueden cambiarse juntos, lo que hace que el programa no encuentre el elemento de configuración.

2. ¿Cuál es el problema con el uso de puntos para unir trazados?

Si el nombre de la clave contiene un punto, la concatenación de puntos provocará ambigüedad. El artículo original recomienda utilizar representaciones inequívocas, como tuplas o punteros JSON.

3. ¿Es suficiente comprobar si el idioma de destino está incluido en la traducción?

no es suficiente. También debe verificar si el conjunto de nombres de clave es consistente con el archivo fuente, si el valor de la ruta no autorizada permanece sin cambios, si el campo de destino sigue siendo una cadena y si las rutas faltantes se informan explícitamente como errores.

4. ¿Se puede reemplazar null con el texto "vacío"?

No poder. null no es una cadena vacía y no debe reemplazarse con texto para facilitar la traducción.

5. ¿Qué se debe utilizar para el mapeo al traducir matrices?

Cuando hay una ID estable, la ID se utiliza primero para el mapeo. Al confiar únicamente en el índice, es posible que se corresponda con una copia incorrecta después de reorganizar los elementos.

📝 Resumen

Antes de traducir la configuración JSON, primero aclare las rutas que permiten la traducción y luego use la lista de verificación de aceptación para verificar las partes sin cambios. Esto hace que sea más fácil localizar el problema cuando algo sale mal.

Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original