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 use the beta version of the framer-plugin package installed as well as project that 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 and Localization Sources. Locales are a language paired with an optional region, like English or English (Canada). Localization sources are the strings from your site, along with their localized value.

Getting Started

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 sources = await framer.unstable_getLocalizationSources()
const helloSource = sources.find(source => source.value === "Hello")

const update = {
    [helloSource.id]: { [frenchLocale.id]: { value: "Bonjour" } }
}

await framer.unstable_setLocalizedValues(update)

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 Localization Import / Export Plugin code as a PR in our open source Plugins repo.

Locales

unstable_getLocales()

unstable_getDefaultLocale()

Localization Sources

unstable_getLocalizationSources()

unstable_setLocalizedValues(update)