Estrategia de localización para App

1. Por qué pensar en la localización específicamente en ChatGPT App

Si has hecho aplicaciones web convencionales, probablemente asocias la localización con i18n clásico: cadenas de la interfaz, un par de formatos de fecha y número, diccionarios, y lo traduces todo con cuidado. En ChatGPT App es más divertido: aquí el participante número tres es el propio modelo LLM. Lee tus descripciones de herramientas, prompts y resultados, saca conclusiones y toma decisiones.

Es decir, el idioma no es solo «cómo mostrar un texto bonito al usuario», sino también «cómo entenderá el modelo qué hace tu herramienta, cuándo invocarla y qué argumentos pasarle». El botón «Comprar» puede traducirse de cualquier manera y el usuario se apañará. Pero si describes de forma difusa un tool que hace un pago, con una mezcla de ruso e inglés, el modelo puede no invocarlo nunca o invocarlo de forma muy distinta a lo esperado.

Otro punto: ChatGPT ya pasa a tu servidor MCP pistas sobre la configuración regional y la ubicación del usuario — _meta["openai/locale"] y _meta["openai/userLocation"]. Esto se hace a nivel de las solicitudes MCP a las herramientas para que puedas adaptar el texto y los datos al idioma y la región del usuario. Es decir, la plataforma ya te «pone» el contexto, y la tarea del desarrollador es aprovecharlo con cabeza.

Por eso, en este módulo miramos la localización como un aspecto arquitectónico de ChatGPT App, y no como «traducimos la UI y nos olvidamos».

2. Capas que hay que localizar

Miremos la App como una tarta por capas. Cada capa puede (y a menudo debe) estar localizada. Para no perdernos, empecemos con un mapa.

Descripción de las capas

Primero, una tabla general y luego lo desglosamos por partes.

De hecho, esta es la primera capa de nuestro mapa de localización: más adelante añadiremos profundidad (cosmética/semántica), idiomas y elementos concretos.

Ahora vamos capa por capa.

Widget UI

La capa más obvia es la interfaz del widget. En GiftGenius esto es:

• títulos de bloques;
• etiquetas de campos («Destinatario», «Presupuesto», «Intereses»);
• botones («Encontrar un regalo», «Restablecer filtros»);
• placeholders en inputs («por ejemplo, colega, madre…»);
• mensajes de error y estados vacíos («No se han encontrado regalos»).

En una aplicación React normal, estos son los primeros candidatos para sacar a diccionarios. Aquí es lo mismo, con la salvedad de que la UI no es toda la App, sino solo una de sus caras.

Más adelante en el módulo haremos una arquitectura i18n normal para el widget, pero ya ahora es importante fijar: no debe haber cadenas en JSX. Incluso si por ahora solo soportas un idioma, es cómodo estructurar los textos de UI desde el principio.

Mini ejemplo con nuestro GiftGenius (aún sin librería i18n real):

type Locale = "en" | "ru";

const uiText = {
  en: {
    title: "GiftGenius: find a perfect present",
    recipientLabel: "Recipient",
  },
  ru: {
    title: "GiftGenius: encuentra el regalo perfecto",
    recipientLabel: "Destinatario",
  },
};

function GiftForm({ locale }: { locale: Locale }) {
  const t = uiText[locale];

  return (
    <div>
      <h2>{t.title}</h2>
      <label>{t.recipientLabel}</label>
      {/* el resto de campos */}
    </div>
  );
}

Aquí aún no hacemos una localización «de verdad», pero ya separamos explícitamente la capa de textos de UI.

Textos de GPT y prompts

La siguiente capa son los textos del sistema y auxiliares, que no son visibles directamente para el usuario, pero influyen mucho en el comportamiento del modelo:

• system‑prompt de tu App («Eres un asistente para elegir regalos…»);
• plantillas de explicaciones que das al modelo («Genera un breve resumen de la elección»);
• follow‑ups preparados y sugerencias para el modelo («sugiere al usuario precisar el presupuesto si…»).

Estos textos también pueden (y a menudo deben) estar localizados. Un ejemplo simple: si el usuario escribe en ruso y tu system‑prompt está completamente en inglés, el modelo se las apañará, pero te privas de control fino sobre el estilo y las formulaciones en ese idioma.

Más adelante, en las lecciones sobre herramientas para localizar prompts y descripciones (prompts/descriptions), veremos cómo jugar con system‑prompts multilingües. Aquí importa remarcar: los prompts son una capa localizable igual que la UI.

Datos y contenido

Después vienen tus datos. Para GiftGenius es el catálogo de regalos: nombres, descripciones, categorías, a veces sugerencias sobre cómo usar el regalo. Para una App comercial también son precios, divisas, unidades de medida, formatos de fechas, etc. En las especificaciones del product feed para ChatGPT (el formato con el que describes tus productos y servicios para la plataforma) estos campos de texto (title, description) y los precios están claramente destacados para poder mostrarlos correctamente a los usuarios dentro de ChatGPT.

Si quieres una App global, en el catálogo de regalos surgen al menos estas preguntas:

• ¿guardamos nombres/descripciones en varios idiomas?;
• ¿cómo elegimos qué idioma servir al usuario?;
• ¿qué hacemos si aún no hay traducción (fallback)?;
• ¿cómo mostramos divisas y formatos de fechas/precios para distintas regiones?

Pequeño ejemplo tipado para el catálogo:

type Locale = "en" | "ru";

interface LocalizedString {
  en: string;
  ru: string;
}

interface Gift {
  id: string;
  title: LocalizedString;
  description: LocalizedString;
  priceCents: number;
  currency: "USD" | "EUR" | "RUB";
}

function getLocalizedTitle(gift: Gift, locale: Locale) {
  return gift.title[locale] ?? gift.title.en;
}

Es decir, la localización no es solo frontend, sino también la estructura de datos en la base y los recursos MCP. Volveremos a esto al hablar del Gateway (puerta de enlace entre ChatGPT y tus servicios) y del servidor MCP.

Descripciones de tools y JSON Schema

La cuarta capa son las descripciones de las herramientas y sus argumentos. A través de ellas el modelo entiende cuándo debe invocar tu tool y qué argumentos pasarle. En MCP son el title, la description de la herramienta y la description en los campos del esquema JSON.

La documentación de Apps SDK subraya que el modelo usa nombres, descripciones y documentación de parámetros para elegir herramientas y construir argumentos.

Ejemplo hipotético de una herramienta de GiftGenius en un servidor MCP con TypeScript:

server.registerTool(
  "suggest_gifts",
  {
    title: "Suggest gifts",
    description: "Suggest 3–5 gift ideas based on recipient profile.",
    inputSchema: {
      type: "object",
      properties: {
        recipient: {
          type: "string",
          description: "Who is the gift for (e.g. mother, colleague)?",
        },
      },
      required: ["recipient"],
    },
  },
  async ({ input }) => { /* ... */ }
);

Ahora todo está en inglés y el modelo lo entiende perfectamente. Pero ¿y si el usuario escribe en ruso? Aun así podrá relacionar «mamá» con recipient, pero con campos complejos y términos de dominio, la probabilidad de error aumenta. En la lección sobre estrategias de localización de descripciones debatiremos por separado: un único idioma inglés en las descripciones frente a descripciones localizadas.

En este punto del mapa de localización es importante simplemente destacar: las descripciones de tools y de JSON Schema también pueden estar localizadas, y eso influye en el comportamiento del modelo.

Commerce y parte legal

Por último, la capa de la que a menudo se acuerdan al final: todo lo relacionado con el dinero y los textos legales:

• nombres de SKU y planes de suscripción;
• campos title/description en los feeds de commerce (productos, servicios, suscripciones);
• Terms of Service, Privacy Policy, Refund Policy;
• correos y notificaciones (email, push) si la App envía algo fuera de ChatGPT;
• estados de pedido y errores de pago que muestras al usuario («Pago rechazado», «No disponible en tu región»).

Aquí hay dos aspectos: UX y ley. El usuario debe entender, en su idioma, a qué accede y por qué paga. Y a la vez, las traducciones deben ser legalmente correctas: a veces Legal exige que solo se consideren jurídicamente válidos los textos en un único idioma (por ejemplo, inglés), y que las demás traducciones sean de carácter «referencial».

En nuestro mapa de localización marcamos necesariamente el contenido de commerce y el legal como una capa aparte, porque a menudo requiere otro proceso (legal, compliance, validación de textos con marketing).

3. Profundidad de la localización: «cosmética» frente a «semántica»

Cuando hablamos de «localizar la App», es útil distinguir dos niveles de profundidad: cosmético y semántico.

Localización cosmética

La «cosmética» es todo lo que cambia el aspecto y la legibilidad, pero apenas cambia el comportamiento del sistema. Ejemplos:

• títulos y etiquetas de botones traducidos;
• placeholders traducidos en inputs;
• mensajes de error «humanos» en la UI;
• texto localizado del banner de marketing en el widget.

En aplicaciones web clásicas, a menudo se paran aquí. En ChatGPT App es una parte importante, pero solo la punta del iceberg.

Localización semántica

La «semántica» son cosas que cambian el comportamiento del modelo y la lógica de la App. Aquí el idioma influye en:

• qué herramienta elegirá el modelo;
• cómo rellenará los argumentos de la herramienta;
• qué datos considerará «correctos» para ese usuario.

Ejemplos de localización semántica:

• system‑prompt en el idioma del usuario, que define el estilo y las reglas de interacción;
• descriptions de tools y sus campos en el idioma del usuario;
• textos de sugerencias/instrucciones diferentes según el contexto cultural;
• ajustes de formatos de fechas/divisas que afectan al parseo y a la generación (31.12.2025 vs 12/31/2025).

Si solo localizaste la cosmética pero no la semántica, tu App puede parecer localizada, pero comportarse como «anglófona» por dentro. En el mapa de localización conviene marcar explícitamente qué elementos son críticos para el comportamiento del modelo.

Para nuestro GiftGenius, por ejemplo:

• la descripción del campo budget en JSON Schema («Budget in the user’s currency») — semántica;
• la etiqueta del botón «Encontrar un regalo» — cosmética (importante para el UX, pero el modelo no la ve).

Ahora que distinguimos entre cosmética y semántica, tiene sentido responder a la pregunta: en cuántos idiomas quieres que funcione tu App.

4. ChatGPT App monolingüe vs multilingüe

Antes de dibujar el mapa, hay que entender la ambición: si haces una App estrictamente monolingüe o si apuntas a una audiencia multilingüe.

App monolingüe

Una App monolingüe es el caso en el que conscientemente soportas solo un idioma. Por ejemplo, solo inglés.

El widget de UI, los prompts, las descripciones de herramientas y los datos — todo en un único idioma. Esto simplifica mucho la vida:

• una única base de código sin ramificaciones por idioma;
• un único esquema de catálogo (sin title_en, title_ru y demás);
• más fácil de mantener y probar.

Pero está claro que la audiencia es limitada. En el caso de ChatGPT App, también significa que, si un usuario llega con otra configuración regional, ChatGPT puede mostrar tu App igualmente, pero tendrá que «trasladar» constantemente el idioma del usuario al idioma interno de la App. En ciertos nichos vale, pero para un servicio de regalos de consumo masivo, difícilmente.

App multilingüe

Una App multilingüe ya es una decisión arquitectónica. Aquí:

• la UI y los textos se muestran correctamente en función del locale del usuario;
• los datos (catálogos, descripciones de productos) también están ligados a idioma/región;
• las descriptions de tools y los system‑prompts pueden variar por idioma;
• los escenarios de commerce tienen en cuenta divisas locales, impuestos, restricciones.

En este caso, un simple if (locale === "ru") repartido por el código ya no es suficiente. Hace falta arquitectura: diccionarios, recursos localizables, un lugar único donde se guarda y procesa locale y userLocation, y acuerdos entre el widget y el servidor MCP.

La documentación de Apps SDK subraya explícitamente que ChatGPT te pasa locale y userLocation en _meta al invocar tus herramientas, precisamente para que puedas elegir en el servidor el idioma y el formato de datos correctos. Ese es el «combustible» de las Apps multilingües.

Pequeña comparación

Para mayor claridad, una mini comparación:

En el curso partiremos de que GiftGenius se vuelve multilingüe (al menos EN/RU) para mostrar un esquema «serio». Pero muchos trucos serán útiles también para una App monolingüe bien hecha, si quieres estar listo para escalar.

5. Dónde influye realmente el idioma en el modelo

Ahora destaquemos los puntos en los que el idioma influye directamente en el comportamiento de ChatGPT.

Idioma del input del usuario vs idioma de las descriptions de tools

Imaginemos:

• el usuario escribe: «Elige un regalo para un colega por 50 euros»;
• tu tool suggest_gifts está descrita solo en inglés;
• campos del esquema: recipient, budget, currency, interests.

El modelo debe:

1. decidir que hay que invocar suggest_gifts;
2. extraer recipient = "colleague", budget = 50, currency = "EUR";
3. serializar correctamente esto en los argumentos JSON.

Si las descriptions son breves y en otro idioma, el modelo se las apaña, pero la probabilidad de rellenar mal los campos es mayor. Por ejemplo, confundir budget con price_limit o pasar texto en el campo interests porque la descripción del campo era ambigua, tipo «Any extra info about the gift».

Con un texto de usuario en ruso y descripciones en inglés, el modelo «salta» constantemente entre idiomas.

Variante con un esquema localizado:

const locale = _meta?.["openai/locale"] ?? "en"; // llega desde ChatGPT 
const isRu = locale.startsWith("ru");

server.registerTool(
  "suggest_gifts",
  {
    title: isRu ? "Selección de regalos" : "Suggest gifts",
    description: isRu
      ? "Sugiere 3–5 ideas de regalo basadas en el perfil del destinatario."
      : "Suggest 3–5 gift ideas based on recipient profile.",
    inputSchema: { /* ... */ },
  },
  async ({ input }) => { /* ... */ }
);

Aquí está simplificado: en realidad es mejor generar las descriptions una vez al iniciar el servidor, y no en cada llamada, pero la idea se entiende. Podemos devolver a ChatGPT descriptions distintas en función del locale para que al modelo le resulte más fácil entender al usuario.

Idioma de los datos vs idioma de la petición

Si tu catálogo de regalos está solo en inglés y el usuario se comunica en ruso, el modelo elegirá nombres y descripciones en inglés. A veces está bien y a veces no. Pero más importante es cómo formateas la salida:

• si muestras al usuario los titles/description originales del servidor;
• o si el modelo los parafrasea en el idioma del usuario en su propio texto;
• o si tu tool ya devuelve el texto localizado en función del locale.

En Apps SDK, el structured content (datos estructurados que devuelves desde los tools) y la respuesta en texto pueden vivir por separado. Puedes devolver datos estructurados (por ejemplo, JSON con los campos del producto) y un texto aparte para el usuario, y el modelo decidirá cómo renderizarlo o parafrasearlo.

La localización puede ocurrir en el nivel del servidor (datos) o en el nivel del modelo (reformular al idioma necesario). Al componer el mapa conviene decidir dónde quieres mantener la «instancia final».

System‑prompt y follow‑ups

Si tu system‑prompt está solo en inglés y el usuario habla ruso, el modelo estará constantemente equilibrando entre dos idiomas. Puede ser aceptable, pero a veces quieres fijar el tono con firmeza: por ejemplo, en la versión en ruso de la App quieres un estilo más informal y en la versión en inglés, uno formal.

Por lo tanto, en el mapa de localización hay que marcar:

• system‑prompt EN;
• system‑prompt RU;
• plantillas de follow‑ups (EN/RU);
• cualquier sugerencia «fija» en el prompt para las herramientas.

6. Mapa de localización para GiftGenius

Ahora juntamos todo lo que ya discutimos sobre capas, profundidad e idiomas en un mapa explícito de localización para GiftGenius. Hagamos lo que luego te tocará hacer para tu App: componer un mapa de localización. La idea es sencilla: una tabla con columnas por capa y tipo de entidad, y filas por elementos concretos.

Ejemplo de mapa

He aquí un mapa simplificado para GiftGenius (EN/RU):

suggest_gifts.description

budget.description

A la izquierda agrupamos por capas y, después, los elementos concretos. La última columna ayuda a entender qué no puede modificarse sin coordinar con el diseñador de prompts/experto en modelos: todo lo marcado como semántica influye en el comportamiento de GPT.

Pequeño esbozo de código

Para vincular el mapa con el código, se puede definir un tipo simple para las entidades localizables:

type LocalizedTextKey =
  | "ui.title"
  | "ui.recipient_label"
  | "error.no_gifts"
  | "prompt.summary_intro";

type Locale = "en" | "ru";

type Messages = Record<Locale, Record<LocalizedTextKey, string>>;

const messages: Messages = {
  en: {
    "ui.title": "GiftGenius: find a perfect present",
    "ui.recipient_label": "Recipient",
    "error.no_gifts": "No gifts found",
    "prompt.summary_intro": "Here’s why these gifts fit:",
  },
  ru: {
    "ui.title": "GiftGenius: encuentra el regalo perfecto",
    "ui.recipient_label": "Destinatario",
    "error.no_gifts": "No se han encontrado regalos",
    "prompt.summary_intro": "Por esto estos regalos encajan:",
  },
};

Estos mismos keys pueden usarse tanto en el widget como al formar prompts en el servidor (siempre que pases el locale a través de la pila — hablaremos de ello en la próxima lección). Así, tu «mapa de localización» se convierte poco a poco en un diccionario tipado, y no en un conjunto disperso de cadenas.

7. Práctica: haz el mapa de localización para tu App

Antes de profundizar en técnicas concretas de i18n y en la arquitectura del Gateway/MCP, es importante hacer un ejercicio aburrido pero muy útil: describir con honestidad qué vas a localizar exactamente.

Un buen enfoque es abrir cualquier editor (Google Sheets, Notion, lo que sea) y crear una tabla con las columnas:

• categoría/capa (UI, prompts, datos, tools, commerce y parte legal, errores);
• elemento (botón concreto, descripción concreta de un campo, endpoint concreto con texto);
• ejemplo de valor EN;
• ejemplo de valor en el segundo idioma (si ya existe o al menos un borrador);
• marca «cosmética/semántica/legalmente importante»;
• owner (quién responde por los cambios: frontend, servidor MCP, product, legal).

Después, recorre tu App y apunta con honestidad todo donde haya texto o el idioma afecte al formato de los datos.

Para GiftGenius saldría una versión ampliada de la tabla anterior. Por el camino, casi seguro que descubrirás un par de lugares «ocultos»:

• constantes de texto en el código de los servidores MCP (por ejemplo, mensajes de error);
• valores por defecto en structuredContent (por ejemplo, categorías que no mostrabas en la UI);
• etiquetas antiguas en tools que ya no corresponden a su comportamiento real.

Este ejercicio es especialmente útil hacerlo antes de conectar la localización con un proceso de negocio real (pagos, activación de suscripciones, documentos legales). Renombrar el tool charge_user en un sistema multilingüe con ACP y textos legales después es mucho más doloroso.

En general, si dibujas el mapa de localización por adelantado y marcas con honestidad qué y en qué idiomas vas a soportar, te ahorras muchos nervios en los siguientes módulos — cuando entren en juego MCP, Gateway, commerce y Store.

8. Errores típicos al planificar la localización

Error n.º 1: pensar que localización = «traducir botones».
Escenario muy frecuente: el equipo saca con cuidado todas las cadenas de la UI a diccionarios, las traduce y se alegra. Mientras tanto, el system‑prompt sigue solo en inglés, las descriptions de tools también, y el catálogo de productos contiene únicamente nombres en inglés. El resultado es que la App parece localizada, pero el modelo por dentro sigue viviendo en su mundo, y el comportamiento continúa siendo anglocéntrico. En la práctica, esto se refleja en recomendaciones extrañas y errores en los argumentos de los tools.

Error n.º 2: no distinguir entre cosmética y semántica.
A veces, product pide «retocar un poco la redacción» en la descripción de una herramienta o en el system‑prompt, y la persona desarrolladora cambia el texto como si fuera una simple etiqueta de la UI. Pero la description de un campo de JSON Schema o una frase en el system‑prompt es parte del contrato con el modelo. Ese tipo de cambios puede alterar radicalmente cómo GPT invoca tu tool. Si no marcas de antemano los elementos semánticos en el mapa de localización, es fácil romper el comportamiento de la App por accidente.

Error n.º 3: empezar con un caos multilingüe sin arquitectura.
Es muy tentador al principio simplemente tirar por el código if (locale === "ru") y poner cadenas en ruso donde haga falta. En un par de semanas, la aplicación se convierte en un «infierno de localización»: en un componente las cadenas están en el diccionario, en otro están incrustadas en JSX, en el servidor hay un tercer esquema de nombres de keys. Más tarde, conectar un sistema i18n en condiciones y unificar todo se vuelve mucho más difícil.

Error n.º 4: olvidar los datos y el dinero.
Incluso equipos con experiencia suelen empezar traduciendo la UI y los prompts, pero pasan por alto que los catálogos de productos, precios, divisas y textos legales también deben tener en cuenta el locale y el userLocation. En las especificaciones del product feed para ChatGPT, precisamente, se fija de forma estricta qué campos de texto y precios se necesitan para mostrar correctamente los productos a los usuarios. Si no prevés el multilingüismo a nivel de datos, luego tendrás que duplicar el feed o hacer migraciones dolorosas.

Error n.º 5: ignorar las señales de la plataforma sobre locale y ubicación.
ChatGPT ya pasa en las llamadas MCP _meta["openai/locale"] y _meta["openai/userLocation"], para que puedas entender en qué idioma y desde qué región interactúan contigo. Algunas personas desarrolladoras igualmente piden al usuario «Elige el idioma de la interfaz» en el primer arranque y no usan esas señales para elegir recursos y precios. El resultado es un UX peor y una arquitectura más compleja de lo necesario.

Error n.º 6: no fijar «owners» de los elementos localizables.
Cuando todo entra en producción, resulta que las traducciones se reparten entre varias personas: frontenders cambian textos de UI, backenders las descriptions de tools, el especialista de ML el system‑prompt, y Legal envía Terms revisados. Si en el mapa de localización no se indica quién responde por cada capa, los cambios empiezan a chocar y algunos textos se actualizan en un sitio y no en otro.