App texts (translations)

This section covers how to translate your app into multiple languages

App texts, short for Application texts and messages, are a kind of database for the text strings you use around your app. You can use them for a single language, or translate every string into other languages to offer users a multilingual app.

App texts are part of Bubble's static data features. That means they aren't dynamic like the database, and your app has to be redeployed whenever one changes. Because of that, they're meant for shorter content like headers, menu options, and button labels, not long strings like articles or product descriptions.

What is localization?

Localization is the process of adapting an app so it works naturally for people in different languages and regions. Translating your text strings is the core of it, which is exactly what app texts let you do. You'll see the term used widely outside Bubble, sometimes shortened to "l10n," so it's worth knowing if you're planning to support more than one language.

App texts become part of your app's codebase and are downloaded to every user on page load. Never use them to store sensitive information.

Using app texts

An app text can be used in any expression, so you can assign it to any element property that accepts a dynamic text. This includes text elements, button and checkbox labels, text input fields, tooltips, and many other places.

In this example, we have a static text string (My dashboard) connected to an app text of the same name. This lets you maintain app-wide strings in one place and translate them into other languages.

In the editor, the property shows App text ([name]), while your running app shows the string you saved for the currently active language.

To use an app text as the Text property of a text element, search for the data source App text.

This also means you can use app texts in workflows, element conditions, and anywhere else you can insert a dynamic expression. In the example above, we selected App text as the data source and My input as the operator. My input is the ID of the specific string we want to show, which means it has to be created first.

Editing app texts

To open the app text editor, go to the Settings tab, in the Languages section. Under General settings you'll find your app's default language and the field on the user that determines their language preference (more on that below).

Under Application texts and messages, you'll find every custom string you've added, along with Bubble's core texts. The left column is the string's ID. In the earlier example, the ID was My input.

The app text editor, in the Languages section of the Settings tab. Custom texts like My Dashboard appear alongside Bubble's core texts, each with an editable string on the right.

1

Open the Settings tab

In the left menu, click the Settings tab.

2

Go to the Languages section

Select the Languages section. Under General settings, you'll find your app's primary language and the language field on the user type. Under Application texts and messages, you'll find your text strings.

3

Find and edit your text

Locate the text you want to edit by its ID in the left column, such as My Dashboard, then edit the string shown in the field on the right. Use the Currently editing messages and texts for dropdown to switch which language you're editing.

Core texts

Core texts are the strings Bubble includes by default. You can change what they say, but you can't delete them, and their IDs stay fixed. They cover the error and informational messages tied to Bubble's core functionality, and they're already translated into every available language.

Bubble's core texts are the built-in messages tied to core functionality, each with an ID like BAD_CSV. You can't delete them or change their IDs, but you can edit the string shown on the right to reword the message or translate it.

Element strings

Some elements and plugins add their own strings, which appear at the bottom of the list. The multi-file uploader plugin, for example, adds strings like Cancel upload and Remove file.

Exporting and importing translations

Bubble lets you export all your language strings to a CSV file, adjust them, and re-import the file. This is an efficient way to have someone else translate your strings without giving them access to the Bubble editor.

Exporting and importing translations

Bubble lets you export your language strings to a CSV file, adjust them, and re-import the file. This is an efficient way to have someone translate your strings without giving them access to the Bubble editor.

Exporting

1

Open the export dialog

Click Export. Bubble asks which languages to include.

2

Select the languages

Every language is selected by default. Use Select All to toggle them all at once, or check individual languages to export only the ones you need.

3

Download the file

Click Export in the dialog to download the CSV.

What the CSV looks like

The exported file has one row per text string and one column per language. The first few columns identify each string:

Column	What it holds
plugin_name	Where the string comes from, such as CORE for Bubble's core texts or USER_TEXTS for your own.
text_name	An internal identifier for the string.
text_code	The string's ID, like My Dashboard or 2FA_TEMP.

After those, each remaining column is one language, headed by its language code (af_za, sq, and so on). The cell where a string's row meets a language's column holds that string's translation in that language. To translate your app, fill in the cells under each language column.

Don't change the text IDs or the column structure. Bubble matches each row back to its string using these, so altering them will break the import. Importing also overwrites all strings, even where a cell is left empty, so keep any string you want to retain in the file.

Importing

1

Open the import dialog

Click Import.

2

Choose your file and delimiter

Set the Data delimiter to match your file (a comma is the default), then click Pick a file to upload and select your CSV.

3

Validate the data

Click Validate data. Bubble checks the file and confirms how many elements are ready to upload.

4

Upload the data

Once validation succeeds, click Upload data to import your translations.

Importing a CSV overwrites all strings, even where a cell is left empty. To keep a string as it was on export, make sure it stays in the file.

How Bubble determines the language

On web apps, Bubble picks the current language using this order of priority:

1. The lang parameter in the URL, if set

2. The current user's language, if the field exists and its value is valid

3. The app's primary language

4. English

Setting up multiple languages

App texts use IETF language tags to identify each language and dialect.

Setting the main language

The main language is what Bubble uses to run your app when no language setting applies. It defines the messages your app can send and show, and it changes how location-sensitive elements behave, for example how dates are formatted in the date input, calendar, and map elements.

Setting the language field on the user

Users don't have a built-in language field, but Bubble lets you add one if you need it. Bubble reads the user's language from this field, so its value has to be a valid IETF language tag, one of the codes in the language dropdown.

The method below uses an option set, which gives your users a clean list of languages to choose from while storing the correct code behind each one. This is just one suggested approach. Any field that returns a valid IETF language tag will work, so you can set this up however suits your app.

1

Create a Languages option set

Create an option set to hold your languages, and give it an attribute for the language code. In this example, the Languages option set has an IETF language tag attribute, and the Spanish option stores the code es_es. Add an option for each language you want to support.

A Languages option set with an IETF language tag attribute. Here, the Spanish option stores the code es_es alongside its display name.

2

Add the field to the User

On the User data type, create a field whose type is your Languages option set. Here it's a field called Language. The field's name doesn't matter, only that it holds a language with a valid code.

3

Configure the language settings

Go to the Settings tab, in the Languages section. Set Language field on the user type to the field you created. Since this field holds an option set rather than a plain text code, also set Attribute for language field to the attribute that holds the code, in this example IETF language tag. Bubble then displays strings in each user's language based on that value.

If the field is empty, Bubble falls back to the language set in Application primary language.

Setting the language with a URL parameter

You can also set the language in the URL with the lang query parameter: add lang=code to the URL, where code is the language code from the Settings tab, in the Languages section. Most, but not all, of these codes follow a two-character, underscore, two-character format.

For example, to run your app in Russian, you'd use https://myapp.com?lang=ru_ru.

App texts in native mobile apps

App texts work in native mobile apps too, so you can localize your content there as well. The main difference is how the app decides which language to show.

On web, Bubble determines the language from a language field on the User data type (as described above). On mobile, it works differently: the app uses the primary language set on the user's device instead.

How it works

When a mobile app launches, Bubble compares the device's primary language against the list of supported languages in your app's mobile settings. If it finds a match, it uses that language's app text translations. If not, it shows content in the primary app language.

You manage supported languages in the Settings tab, under Supported languages.

Supported languages and dialects

Some languages have regional variations, known as dialects. Spanish, for example:

• es_es (Spanish, Spain)

• es_mx (Spanish, Mexico)

• es_ar (Spanish, Argentina)

Bubble lets you set a specific dialect for each supported language, using the Select base language and Select region or dialect fields. A user's device, though, might report only a base language like es, with no region. To handle that, each supported language has a Select fallback language setting that decides which dialect to use when the device gives only the base language.

For example, if you support es_mx and es_ar and a device reports only es, Bubble uses the fallback dialect you set, such as es_mx.

How mobile chooses a language, in short

Device reports	What the app shows
A supported dialect	That dialect's translation
A base language only	The fallback dialect you defined
No match	The app's primary language

Updating supported languages

• Adding a supported language can go out in an over-the-air (OTA) update.

• Translations for system-level prompts, like permission messages, need a new build, since those values are compiled into the native binary.

FAQ: App texts

What does Bubble show if a string isn't translated into the active language?

It displays (no translation) in place of the string. Bubble's error console, in the bottom-right of the debugger, also flags a warning when you preview the page.

What happens if the user's language field is empty?

If the field is empty or returns an invalid language code, Bubble falls back to the language set in Application primary language.

How do app texts affect performance?

Your app texts become part of your app's JavaScript source files, so they're downloaded to every user who opens a page. For performance, Bubble only downloads the text in the language the user has selected, which is why changing the language requires a page load: a new JavaScript file has to be generated and downloaded.

App texts are no more taxing than putting the string directly on an element, and if a string is used in several places, they're lighter, since it's only stored once. Even if you don't plan to translate your app, keeping all your strings in one place can be useful.

Do app texts support right-to-left (RTL) writing?

Yes. App texts support RTL languages like Arabic, Hebrew, and Urdu. You may need to adjust your design when switching between LTR and RTL languages, so we recommend testing your app in both.

Known issue: right-to-left (RTL)

When text is displayed in RTL and you apply certain operations or changes, it may switch back to a left-to-right display. If RTL support is a priority, preview your pages in run mode to confirm they display correctly.

I changed an app text, so why isn't it showing in my live app?

A few things to check:

• Changes appear in Development after you refresh the page, and in Live after you deploy and refresh.

• Confirm you're viewing the app in the same language as the string you changed.

• Confirm the Saving indicator next to the edit menu reads Saved, so you know the change synced to Bubble's server. If it doesn't, check your internet connection.