Localization (Beta)

This page is an in-progress document for using the Localization Plugin APIs, allowing you to programmatically manage your Localizations in Framer. We’ll be iterating on this page and the APIs themselves as we gather feedback. Please let us know in Slack if you experience any issues while using these APIs.

Installation

To start you will need to ensure that your project is opted into the Beta. You can opt-in any specific project to the Beta Channel by opening the Main Menu and clicking on Use Beta. Once this is enabled, you should see a Status Bar appear below, indicating your project now has access to all Beta features.

npm

Important: Only use these APIs on new projects or duplicates of existing projects.

Concepts

The key pieces of Localization in Framer are Locales, Localization Groups, and Localization Sources. Locales are a language paired with an optional region, like English or English (Canada). Localization groups are things like pages or CMS items that contain one or more Localization sources. Localization sources are the strings from your site, along with their localized value.

Examples

The core part of this API is the getting and setting of Localization sources for the Locales in the project. The following is a basic example of updating every Localization Source for the word “Hello” within the French Locale.

// Find Locale to update
const locales = await framer.unstable_getLocales()
const frenchLocale = locales.find(locale => locale.code === "fr")

// Filter specific sources to update
const groups = await framer.unstable_getLocalizationGroups()

// Collect changes in localization data object
const localizationData: LocalizationData = { valuesBySource: {} }

// Update French localization for all matching sources
for (const group of groups) {
  for (const source of group.sources) {
    if (source.value === "Hello") {
        localizationData.valuesBySource[source.id] = {
          [frenchLocale.id]: { action: "set", value: "Bonjour" }
        }
    }
  }
}

await framer.unstable_setLocalizationData(localizationData)

It is also possible to toggle the visibility of groups in Locales. The following shows how you can, for example, hide all collection items in the French Locale.

const localizationData: LocalizationData = { hiddenLocalesByGroup: {} }

for (const group of groups) {
    if (group.type === "collection-item") {
        localizationData.hiddenLocalesByGroup[group.id] = [frenchLocale.id]
    }
}

await framer.unstable_setLocalizationData(localizationData)

Note: During the beta period the API functions are prefixed with unstable_. Make sure to update the framer-plugin package often during the beta.

These concepts can be extended to achieve a wide range of functionality within Plugins. For a more complete example using these APIs, you can browse our example Locale Import & Export Plugin code as a PR in our open source Plugins repo.

Locales

unstable_getLocales()

unstable_getDefaultLocale()

Localization

unstable_getLocalizationGroups()

unstable_setLocalizationData(localizationData)