De dónde obtener la locale: openai/locale, _meta["openai/userLocation"]

1. Por qué es importante obtener la locale de la plataforma y no preguntarla al usuario cada vez

Si abordamos la localización «a la antigua», la lógica suele ser: mostrar un modal «Elige idioma» y guardar el resultado en localStorage. En ChatGPT Apps el enfoque es otro: ya tenemos una plataforma inteligente que ofrece generosamente señales sobre idioma y región. Hay que aprender a usarlas y no molestar al usuario con preguntas innecesarias.

ChatGPT añade al contexto de cada solicitud a tu App:

• la configuración regional preferida del usuario (idioma + región), en el campo openai/locale / _meta["openai/locale"];
• la geolocalización/región del usuario, en el campo _meta["openai/userLocation"].

En el lado del widget (frontend) obtienes la locale a través de window.openai o de un hook del SDK; en el lado MCP/backend, mediante _meta en la solicitud MCP.

El escenario normal queda así: el usuario escribe «Encuentra un regalo para mi madre por hasta 50 €». ChatGPT ya conoce su locale y userLocation, la plataforma transmite esas señales a tu App y tú:

• muestras la UI en un idioma comprensible,
• cargas el idioma correcto del catálogo,
• formateas los precios en la moneda y el formato adecuados.

Sin un diálogo aparte de «Por cierto, ¿cuál es su idioma?».

2. Señal n.º 1: openai/locale — idioma y región del usuario

Qué es este campo y cómo se ve

openai/locale es una cadena en formato BCP‑47, que seguro has visto: "en", "en-US", "ru", "ru-RU", "uk-UA", etc.

Importa que la plataforma:

• puede enviar solo el idioma ("en", "ru"),
• o idioma + región ("en-US", "en-GB", "fr-CA").

BCP‑47 es un estándar con el que funcionan muy bien tanto las API Intl del navegador como la mayoría de bibliotecas i18n. Es decir, openai/locale se puede pasar casi directamente a Intl.NumberFormat, al motor de traducciones y a tus tools.

Dónde está disponible la locale en el widget

En la UI personalizada que se renderiza dentro de ChatGPT, el Apps SDK proporciona el objeto global window.openai, donde existe locale.

Normalmente se ve así (TypeScript, Next.js 16, nuestro widget GiftGenius):

// src/app/widgets/gift-widget.tsx
declare global {
  interface Window {
    openai?: { locale?: string };
  }
}

function getOpenAiLocale(): string {
  if (typeof window === "undefined") return "en";
  return window.openai?.locale || "en";
}

En una aplicación real es más sencillo crear un hook que funcione tanto en la sandbox de ChatGPT como en Storybook:

// src/app/hooks/useOpenAiLocale.ts
import { useEffect, useState } from "react";

export function useOpenAiLocale(defaultLocale: string = "en") {
  const [locale, setLocale] = useState(defaultLocale);

  useEffect(() => {
    if (typeof window === "undefined") return;
    const next = window.openai?.locale || defaultLocale;
    setLocale(next);
  }, [defaultLocale]);

  return locale;
}

Ahora, en cualquier componente:

import { useOpenAiLocale } from "../hooks/useOpenAiLocale";

export function GiftHeader() {
  const locale = useOpenAiLocale();

  return (
    <h2>
      {/* más adelante aquí irá t('titles.gift_search') */}
      {locale.startsWith("ru") ? "Búsqueda de regalos" : "Gift search"}
    </h2>
  );
}

En la lección 4 sacaremos todas las cadenas a diccionarios, pero ya ahora hemos ligado la UI a una señal real de la plataforma, y no al aleatorio navigator.language. Este hook es muy específico; en un proyecto real conviene construirlo sobre un mecanismo más general de acceso a los globales de ChatGPT — volveremos a ello en una sección aparte más abajo.

Dónde está disponible la locale en MCP/backend

Cuando ChatGPT invoca una herramienta MCP, el SDK pasa _meta["openai/locale"] en la solicitud JSON‑rpc. En un servidor TypeScript (nuestro MCP de GiftGenius) esto suele estar disponible en el segundo argumento del manejador de la herramienta.

Ejemplo:

// src/mcp/server.ts
import { McpServer } from "@openai/mcp-sdk";

const server = new McpServer();

server.registerTool(
  "suggest_gifts",
  {
    title: "Selección de regalos",
    description: "Propone una lista de regalos según las preferencias",
    inputSchema: {
      type: "object",
      properties: {
        recipient: { type: "string" },
        budget: { type: "number" }
      },
      required: ["recipient", "budget"]
    }
  },
  async ({ input }, extra) => {
    const locale = extra?._meta?.["openai/locale"] || "en";
    // a continuación podemos cargar el catálogo correcto
    const gifts = await loadGiftCatalog(locale);
    // ...
    return {
      content: [
        {
          type: "text",
          text: `Found ${gifts.length} gifts for locale ${locale}`
        }
      ],
      structuredContent: { gifts }
    };
  }
);

Así, la locale vive a lo largo de toda la pila: ChatGPT → Apps SDK → tu servidor MCP.

Insight

Cada mcp-tool en el servidor tiene un parámetro extra, donde el servidor MCP coloca todos los datos que no cupieron en el inputSchema. He aquí un ejemplo de dicho objeto:

{
  sessionId: undefined,			// siempre undefined, usa `openai/subject` más abajo
  _meta: {
    'openai/userAgent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36',
    'openai/locale': 'en-US',		// locale del ordenador del usuario; puede no coincidir con el idioma del chat
    'openai/userLocation': {		// ubicación del usuario bastante precisa
      city: 'London',
      region: 'London City',
      country: 'GB',
      timezone: 'Europe/London',
      latitude: '5.45466',
      longitude: '-0.52380'
    },
    timezone_offset_minutes: -240,	// desplazamiento del huso horario
    'openai/subject': 'v1/sEtRuS92UEOPNdwzEUZORfeOKf7XSk2KZoIUGfAsb68BzZ8h5FAOgrH'	// esto es el sessionId
  },
  authInfo: undefined,
  requestId: 1,
  requestInfo: {
    headers: {
      accept: 'application/json, text/event-stream',
      'accept-encoding': 'gzip, deflate, br, zstd',
      'access-control-allow-headers': '*',
      'access-control-allow-methods': 'GET,POST,PUT,DELETE,OPTIONS',
      'access-control-allow-origin': '*',
      'content-length': '542',
      'content-type': 'application/json',
      host: 'test.ngrok.app',					// dominio propio de la aplicación
      'mcp-protocol-version': '2025-11-25',	
      traceparent: '00-69399d3a000000004fb8cc13dc3a2203-8748a8698107eb34-00',
      tracestate: 'dd=s:-1;p:01514e334c1ccef5;t.dm:-3',
      'user-agent': 'openai-mcp/1.0.0',
      'x-datadog-parent-id': '6089244476286233754',
      'x-datadog-sampling-priority': '-1',
      'x-datadog-tags': '_dd.p.tid=69399c3a00000000,_dd.p.dm=-3',
      'x-datadog-trace-id': '5744565710382309891',
      'x-forwarded-for': '199.210.139.232',
      'x-forwarded-host': 'test.ngrok.app',
      'x-forwarded-port': '3001',
      'x-forwarded-proto': 'https'
    }
  },
}

Es posible que parte de los encabezados los haya rellenado ngrock, pero sigue habiendo muchos datos interesantes.

3. Señal n.º 2: _meta["openai/userLocation"] — la ubicación del usuario

Estructura y significado

_meta["openai/userLocation"] es un objeto con información geográfica: país, región, ciudad, zona horaria e incluso coordenadas. Aproximadamente así:

{
  "city": "London",
  "region": "England",
  "country": "GB",
  "timezone": "Europe/London",
  "latitude": 51.5074,
  "longitude": -0.1278
}

Campos principales que realmente usarás en GiftGenius:

• country — código de país ISO de dos letras, crítico para surtido y moneda;
• timezone — útil para formatos de fecha/hora y recordatorios.

Insight

Comprobado experimentalmente: la determinación de userLocation funciona con mucha calidad. Los datos llegan en cada invocación del MCP-tool mediante el parámetro extra._meta["openai/userLocation"]. Puedes contar con ellos al desarrollar tus aplicaciones.

Cómo usar userLocation en herramientas MCP

En el servidor MCP, userLocation vive en _meta["openai/userLocation"] junto a _meta["openai/locale"].

Ampliemos el ejemplo de nuestra herramienta:

server.registerTool(
  "suggest_gifts",
  { /* esquema como arriba */ },
  async ({ input }, extra) => {
    const meta = extra?._meta ?? {};
    const locale = (meta["openai/locale"] as string) || "en";
    const userLocation = meta["openai/userLocation"] as
      | { country?: string; city?: string }
      | undefined;

    const country = userLocation?.country || "US";

    const gifts = await loadGiftCatalog(locale, country);

    return {
      content: [
        {
          type: "text",
          text: `Found ${gifts.length} gifts for locale=${locale}, country=${country}`
        }
      ],
      structuredContent: { gifts }
    };
  }
);

La función loadGiftCatalog(locale, country) ya puede:

• elegir el archivo JSON adecuado: gift_catalog.en-US.json, gift_catalog.ru-RU.json,
• filtrar los artículos que no se pueden entregar a ese país,
• elegir la moneda base.

Más adelante, en los módulos de comercio, con base en country seleccionarás las reglas fiscales y mapearás a los SKU adecuados, pero desde el punto de vista arquitectónico seguirás apoyándote en la misma señal — country.

Cómo complementa userLocation a locale

Ejemplo clásico:

locale = "en", userLocation.country = "DE".

La lógica puede ser la siguiente:

• UI y sugerencias en inglés (respetar locale);
• formato y moneda en euros, porque el usuario está físicamente en Alemania;
• lista de regalos — solo los que se entregan en DE.

En GiftGenius esto puede expresarse con una pequeña función auxiliar:

export function deriveCurrency(locale: string, country?: string): string {
  if (country === "DE") return "EUR";
  if (country === "JP") return "JPY";   
  if (locale === "zh_CN") return "CNY"; 
  return "USD";
}

Y usarla en backend/frontend para formatear precios:

const currency = deriveCurrency(locale, country);
const formatted = new Intl.NumberFormat(locale, {
  style: "currency",
  currency
}).format(price);

En el backend ya aprendimos a usar locale y country para elegir el catálogo y la moneda. Después es importante llevar con cuidado esas mismas señales a la UI del widget para que el usuario vea textos y precios en el formato esperado.

4. Cómo obtener locale y userLocation en el widget de GiftGenius

Ya vimos cómo locale y userLocation viven en el lado MCP e influyen en catálogos y moneda. Ahora veamos cómo tomar locale en el widget de GiftGenius y usarla directamente en el UI de React.

Importante: en el widget tenemos acceso directo solo a locale (mediante window.openai y hooks del SDK). userLocation vive en _meta y se usa en el lado MCP/backend — con ello ya trabajamos arriba.

En el Apps SDK además del window.openai «crudo» hay utilidades en forma de hooks de React. La documentación describe hooks como useOpenAiGlobal("locale"), que extraen valores del contexto global de ChatGPT hacia los componentes de React.

Vamos a modelar nosotros mismos ese hook para entender qué ocurre bajo el capó.

Hook básico useOpenAiGlobal

Antes hicimos el useOpenAiLocale especializado. En la práctica es más cómodo tener un solo hook universal para acceder a los globales de ChatGPT — sobre él es fácil construir useOpenAiLocale y otros envoltorios. Imaginemos un hook así:

// src/app/hooks/useOpenAiGlobal.ts
import { useEffect, useState } from "react";

type OpenAiGlobals = {
  locale?: string;
  // aquí más tarde podemos añadir theme, userAgent, etc.
};

export function useOpenAiGlobal<K extends keyof OpenAiGlobals>(
  key: K,
  fallback?: NonNullable<OpenAiGlobals[K]>
): NonNullable<OpenAiGlobals[K]> {
  const [value, setValue] = useState<NonNullable<OpenAiGlobals[K]>>(
    (fallback ?? "") as NonNullable<OpenAiGlobals[K]>
  );

  useEffect(() => {
    if (typeof window === "undefined") return;
    const globals = (window.openai || {}) as OpenAiGlobals;
    const next = globals[key] ?? fallback;
    if (next !== undefined) {
      setValue(next as NonNullable<OpenAiGlobals[K]>);
    }
  }, [key, fallback]);

  return value;
}

Ahora useOpenAiGlobal("locale", "en") nos da el valor actual de locale con el valor por defecto "en".

Uso en el widget de GiftGenius

Hagamos un pequeño componente que muestre un saludo localizado y la locale actual para depuración:

// src/app/widgets/GiftWelcome.tsx
"use client";

import React from "react";
import { useOpenAiGlobal } from "../hooks/useOpenAiGlobal";

export function GiftWelcome() {
  const locale = useOpenAiGlobal("locale", "en");

  const greeting =
    locale.startsWith("ru") || locale.startsWith("uk")
      ? "¡Hola! Te ayudaré a encontrar un buen regalo."
      : "Hi! I’ll help you find a great gift.";

  return (
    <div>
      <p>{greeting}</p>
      <small style={{ opacity: 0.6 }}>Debug locale: {locale}</small>
    </div>
  );
}

De momento sin diccionarios ni bibliotecas i18n — eso vendrá después. Ahora lo importante es que ya sabemos obtener el idioma de ChatGPT, y no de suposiciones aleatorias.

5. Cuándo conviene preguntar explícitamente al usuario por el idioma

Si openai/locale y userLocation son tan buenos, ¿podemos no preguntar nunca al usuario en qué idioma quiere trabajar? Por desgracia, a veces hay que hacerlo.

Cuando las señales no bastan

Hay varias situaciones típicas:

• La cuenta de ChatGPT es en inglés (locale = "en"), pero el usuario escribe en ruso. El modelo responde en ruso, pero tú entregas la UI en inglés.
• El usuario está en Alemania (userLocation.country = "DE"), locale = "en", y tú puedes ofrecer interfaz en alemán y en inglés.
• La aplicación es crítica respecto al idioma de comunicación: psicoterapia, asesoría legal, formación. Allí la precisión importa más que la comodidad del autodetección.

En esos casos es apropiado hacer una pregunta breve y cortés una sola vez al comienzo, y recordar la elección.

Cómo plantear la pregunta de manera sutil

Normalmente se formula de forma simple y visual, por ejemplo:

• «¿En qué idioma le resulta más cómodo: English o ruso?»
• «Hemos detectado su idioma como English. ¿Quiere cambiar a otro?»

En un ChatGPT App se puede hacer de dos maneras:

• A través de la UI del widget: dibujar un pequeño selector de idioma en la parte superior.
• Mediante un mensaje de seguimiento (follow‑up) en el chat en nombre de la App: enviar el texto con la pregunta y luego procesar la respuesta.

Código: selección simple de idioma en GiftGenius

Hagamos un componente conmutador que:

• tome el idioma inicial de locale,
• permita al usuario elegir entre ru o en,
• guarde la elección en el estado del widget (por ahora solo en el estado de React).

// src/app/widgets/LanguageSwitcher.tsx
"use client";

import React, { useState, useEffect } from "react";
import { useOpenAiGlobal } from "../hooks/useOpenAiGlobal";

type SupportedLocale = "en" | "ru";

export function LanguageSwitcher(props: {
  onChange?: (locale: SupportedLocale) => void;
}) {
  const initialLocale = useOpenAiGlobal("locale", "en");
  const [locale, setLocale] = useState<SupportedLocale>("en");

  useEffect(() => {
    const normalized: SupportedLocale = initialLocale.startsWith("ru")
      ? "ru"
      : "en";
    setLocale(normalized);
    props.onChange?.(normalized);
  }, [initialLocale, props]);

  const handleChange = (next: SupportedLocale) => {
    setLocale(next);
    props.onChange?.(next);
  };

  return (
    <div style={{ marginBottom: 8 }}>
      <span style={{ marginRight: 8 }}>
        {locale === "ru" ? "Idioma:" : "Language:"}
      </span>
      <button
        type="button"
        onClick={() => handleChange("en")}
        style={{ fontWeight: locale === "en" ? "bold" : "normal" }}
      >
        EN
      </button>
      <button
        type="button"
        onClick={() => handleChange("ru")}
        style={{ fontWeight: locale === "ru" ? "bold" : "normal", marginLeft: 4 }}
      >
        RU
      </button>
    </div>
  );
}

Y en el widget principal de GiftGenius ya puedes elegir textos/diccionario según selectedLocale, y no según los datos «crudos» de ChatGPT.

En futuras lecciones sustituirás el estado local por un almacenamiento más robusto (por ejemplo, pasarás el idioma seleccionado al MCP / Gateway mediante _meta["openai/subject"]), pero el patrón seguirá siendo el mismo.

6. Cómo pasar locale y userLocation al backend y conservarlos

Las señales de ChatGPT llegan «desde arriba», pero la vida no termina ahí. Luego hay que llevar esos datos a tus herramientas y servicios, no perderlos por el camino y no obligar al modelo a adivinar el idioma de nuevo.

Campo explícito locale en los argumentos de las tools

El truco más fiable es añadir locale (y si quieres country) como campos separados en el inputSchema de la herramienta. Así el modelo recibe una señal explícita: «hay que rellenar este campo».

server.registerTool(
  "suggest_gifts",
  {
    title: "Gift suggestions",
    description: "Suggest gifts based on recipient and budget",
    inputSchema: {
      type: "object",
      properties: {
        recipient: { type: "string" },
        budget: { type: "number" },
        locale: {
          type: "string",
          description: "Current user UI locale, BCP-47 (e.g. en-US, fr-FR)"
        },
        country: {
          type: "string",
          description: "ISO country code (e.g. US, DE)"
        }
      },
      required: ["recipient", "budget"]
    }
  },
  async ({ input }, extra) => {
    // Si el modelo no rellenó locale/country, nos cubrimos con _meta:
    const meta = extra?._meta ?? {};
    const locale = input.locale || (meta["openai/locale"] as string) || "en";
    const country =
      input.country ||
      (meta["openai/userLocation"] as any)?.country ||
      "US";

    // ...
  }
);

Esto reduce la «magia» dentro del servidor: ve con claridad los argumentos que el modelo piensa usar.

Almacenamiento de locale a nivel de sesión/usuario

En una arquitectura con MCP Gateway (módulos futuros) es habitual guardar el «estado del cliente»: locale, currency, preferencias. Ahora nos basta con entender la idea: una vez leídas las señales de ChatGPT, las usamos como parte del estado de sesión, y no las recalculamos cada vez.

Pseudocódigo aproximado:

// gateway.ts
const sessionState = new Map<string, { locale: string; country?: string }>();

function onMcpRequest(request: any) {
  const subject = request._meta?.["openai/subject"]; // id de usuario anónimo
  const locale = request._meta?.["openai/locale"] || "en";
  const country = request._meta?.["openai/userLocation"]?.country;

  if (subject) {
    sessionState.set(subject, { locale, country });
  }

  // después pasamos locale/country al servidor MCP concreto
}

En el marco de esta lección no necesitas implementar el Gateway; basta con entender que locale y userLocation son candidatos a ese «estado de sesión».

Insight

Datos experimentales: request._meta?.["openai/locale"] muestra la locale actualmente establecida del usuario. El idioma de comunicación se puede obtener como parámetro de la tool mediante el inputSchema.

En mi equipo tenía establecida la locale EN, y hablaba con ChatGPT en alemán (DE). En consecuencia:

• request._meta?.["openai/locale"] era EN
• locale, obtenida como parámetro de la tool mediante inputSchema, era DE

7. Locale vs autodetección del idioma por el texto

A veces tienta la idea: «Detectemos el idioma por el texto del usuario, total la LLM lo puede todo». En la práctica casi siempre es peor que apoyarse en openai/locale.

Las razones son bastante prosaicas:

• el usuario puede escribir en una mezcla de idiomas;
• las diferencias finas (uk-UA vs ru-RU) se detectan mal por un solo mensaje;
• ChatGPT ya hizo ese trabajo por ti y envió locale.

La autodetección es útil como fallback si openai/locale llega en un formato extraño o falta (algo poco frecuente hoy), pero no conviene basar en ello la lógica principal. Regla gruesa:

• primero miramos openai/locale como «verdad»;
• luego tenemos en cuenta userLocation (moneda, surtido);
• y solo en casos muy dudosos miramos además el idioma del último mensaje.

8. Diferentes combinaciones de locale y userLocation: tabla de escenarios

Para consolidar, veamos cómo debería comportarse GiftGenius en distintos escenarios.

en-US

US

USD

uk-UA

UA

UAH

en

DE

EUR

ru-RU

DE

EUR

en

USD

Esta perspectiva te servirá más adelante cuando hablemos de comercio, pero ya ahora se ve lo fácil que es cambiar el comportamiento, simplemente proporcionando diferentes locale y country.

9. Pequeño diagrama del flujo de señales de la locale

Para ordenar ideas, veamos un esquema simplificado:

flowchart TD
  U[Usuario<br/>escribe un mensaje] --> C[ChatGPT]
  C -->|determina| L[openai/locale<br/>+ userLocation]
  L -->|pasa| W["Widget (Next.js)"]
  L -->|pasa a través de _meta| S[MCP Server]

  W -->|locale| UI[GiftGenius UI<br/>textos + formato de números]
  S -->|locale + country| DATA[Catálogos, precios, filtros]

  style L fill:#e0f7ff,stroke:#00a
  style W fill:#f7fff0,stroke:#4b4
  style S fill:#fdf0ff,stroke:#b4

Es importante notar: en este esquema no aparece ningún modal «Elige idioma». Hace falta solo como capa adicional cuando las señales contradicen las expectativas del usuario.

10. Práctica: qué puedes hacer ahora mismo en tu App

Para que la lección no se quede en teoría, un breve checklist práctico para GiftGenius:

• En el widget: añadir el hook useOpenAiGlobal("locale") o análogo y, al menos en un lugar, introducir una bifurcación RU/EN para el texto.
• En el servidor MCP: en una de las herramientas existentes (suggest_gifts) obtener _meta["openai/locale"] y _meta["openai/userLocation"], registrarlos en log y usarlos para elegir el catálogo.
• Escribir una función sencilla deriveCurrency(locale, country) y usarla en un lugar al formatear el precio.

No hace falta construir desde ya un motor i18n completo con 15 idiomas: el objetivo ahora es aprender a usar honestamente las señales de la plataforma.

11. Errores habituales al trabajar con locale y userLocation

Error n.º 1: ignorar por completo openai/locale y basarse solo en navigator.language.
Esto lo hace quien está acostumbrado a aplicaciones web «normales». En ChatGPT el usuario puede no abrir nada en el navegador, y navigator.language de tu lado es el idioma del servidor túnel o de Vercel, no el del usuario. Como resultado, la UI está «misteriosamente» en inglés, aunque ChatGPT te envía de forma estable ru-RU.

Error n.º 2: preguntar cada vez al usuario «¿en qué idioma le resulta más cómodo?»
Si en cada chat la primera réplica del widget es una encuesta de idioma, los usuarios empiezan a sentirse en un aeropuerto, donde les preguntan cinco veces seguidas si olvidaron el equipaje. La plataforma ya sabe el idioma y la región: basta con respetar openai/locale y preguntar solo ante un conflicto evidente (por ejemplo, una petición en ruso con locale = "en").

Error n.º 3: guardar el idioma elegido solo en la UI y no pasarlo a las herramientas MCP.
El widget puede estar en ruso, pero el servidor seguir devolviendo el catálogo en inglés porque no sabe del cambio de idioma. Piensa siempre en el recorrido extremo a extremo: si hay un selector en la UI, el resultado debe llegar al backend — ya sea en los argumentos de la herramienta, ya sea a través de la sesión del Gateway.

Error n.º 4: intentar «adivinar» el idioma solo por el texto de los mensajes, ignorando openai/locale.
La autodetección por texto puede funcionar bien… mientras el usuario escriba un inglés limpio. En cuanto haya mezclas o frases similares, el resultado empezará a variar. openai/locale es ya una estimación preparada y bastante fiable, proporcionada por la plataforma. Debe considerarse la fuente principal de verdad, y el detector de texto, solo una señal adicional.

Error n.º 5: mezclar la lógica de negocio y la localización con if (locale === 'ru') { ... } por todo el código.
En esta lección aún lo hacemos un poco por simplicidad, pero es importante planificar desde el principio que las cadenas, los formatos y los catálogos deben estar separados de la lógica de negocio. De lo contrario, en unos meses te encontrarás con código donde cada función empieza con if (locale.startsWith("ru")), y añadir otro idioma será doloroso. En la lección 44 curaremos justamente este problema, recordando que ya tenemos la fuente de locale y sabemos usarla.