Can we add/create a locale for a record in sandbox env through CMA

🆘 Support
2

Hello @rohan.prasad and welcome to the community! :slight_smile:

Yes, you can add a new locale value to a record in a sandbox using only the CMA. When this works in primary but not in a sandbox it almost always comes down to either the client not pointing to the sandbox environment, the target locale not existing in that sandbox, or the update payload not touching every localized field. Make sure your CMA client is initialized with the sandbox environment, otherwise calls will hit primary by default. Here is a minimal backend example with @datocms/cma-client-node, plus verbose logging so you can see exactly what is being sent and returned: https://www.datocms.com/docs/content-management-api/setting-the-environment and https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients

import { buildClient, LogLevel } from "@datocms/cma-client-node";

const client = buildClient({
  apiToken: process.env.DATOCMS_CMA_TOKEN,
  environment: "my-sandbox-environment",
  logLevel: LogLevel.BODY,
});

Use the CMA to confirm the sandbox has the locale you’re trying to write. You can read and update project locales through the Site resource. If the locale is missing in the sandbox, add it there first or run the same migration that added it in primary. Docs for the Site resource are here: https://www.datocms.com/docs/content-management-api/resources/site

// Check locales available in the sandbox
const site = await client.site.find();
console.log(site.locales); // e.g. ["en", "it"]

// Add a missing locale to the sandbox if needed:
const targetLocale = "de";
if (!site.locales.includes(targetLocale)) {
  await client.site.update({
    locales: [...site.locales, targetLocale],
  });
}

When you “add a locale on a record” through the CMA you need to send all localized fields with the new locale key present, merging with the existing locales for each field. If you don’t include a localized field at all in the payload, that field will not gain the new locale for that record. The update semantics and examples are outlined here: https://www.datocms.com/docs/content-management-api/resources/item/update and the localization rules here: https://www.datocms.com/docs/general-concepts/localization

// Discover which fields are localized for this record's model
const record = await client.items.find(recordId);
const itemTypeId = record.item_type.id;
const fields = await client.fields.list(itemTypeId);
const localizedFieldApiKeys = fields.filter(f => f.localized).map(f => f.api_key);

// Build an update that preserves existing values and adds the new locale
const newLocale = "de";
// Suppose your translation service returns a map of apiKey -> translated value
const translations: Record<string, unknown> = {
  title: "Mein Titel",
  content: "Artikelinhalt",
  // other fields you translated...
};

const updatePayload: Record<string, any> = {};
for (const apiKey of localizedFieldApiKeys) {
  const current = (record as any)[apiKey] || {};
  const translated =
    Object.prototype.hasOwnProperty.call(translations, apiKey)
      ? translations[apiKey]
      : null; // use null if you don't have a translation yet, see note below
  updatePayload[apiKey] = { ...current, [newLocale]: translated };
}

await client.items.update(recordId, updatePayload);

If your project or field validations require values in every locale, you must provide a non null value for each localized field. If they do not, you can send null for fields you have not translated yet and the locale will still be registered on the record. There is a useful community discussion about this behavior here: https://community.datocms.com/t/bug-invalid-locales-when-updating-record-via-api/4523

One more sanity check that helps in sandboxes. Schema can drift between environments. If a field is localized in primary but not localized in the sandbox, sending a per locale object for that field will not have any effect in the sandbox. Reading the field definitions through the CMA, as shown above, is the quickest way to confirm that f.localized is true for the fields you’re updating. If it differs, align the sandbox schema by applying the same migration you used in primary. Migration overview is here: https://www.datocms.com/docs/scripting-migrations/introduction

If you can share the sandbox name, the model API key, and the exact updateObject you’re sending, I’m happy to help tailor a payload that reliably adds the locale in that environment.

Best,