How to Set Mastodon Instance Default Language Per New User

When you run a Mastodon instance, new users register with a default language setting that affects their entire experience. The default language determines the interface language, the content language filter for the federated timeline, and the suggested accounts shown during onboarding. Many instance administrators want to set a different default language than the server locale, such as English for a multilingual community. This article explains how to configure the default language for new users using the Mastodon admin settings and environment variables.

How Mastodon Assigns a Default Language to New Users

Mastodon determines the language for a new user account through a priority chain. The system first checks the browser’s Accept-Language header sent during registration. If the browser language matches one of the 70+ supported locales, Mastodon uses that language for the interface and sets it as the user’s posting language. If no match is found, Mastodon falls back to the instance’s default language setting. If that setting is empty, the server uses the system locale of the operating system.

The default language setting affects three areas: the registration page language, the initial interface language for the new user, and the default language tag applied to all new posts until the user changes it. Changing the default language does not retroactively apply to existing users. Each user can override their language in Preferences > Appearance > Language.

Supported Languages and Locale Codes

Mastodon uses standard BCP 47 locale codes. The most common codes are en for English, de for German, fr for French, ja for Japanese, and es for Spanish. A full list of supported locales is available in the Mastodon source code under the config/locales directory. The default language value must match one of these codes exactly. For example, setting the value to en works, but setting it to eng or english fails silently.

When the Browser Language Overrides the Instance Default

The browser Accept-Language header takes precedence over the instance default. If a user registers with a browser set to French, Mastodon assigns the French locale even if the instance default is English. The instance default only applies when the browser language is not supported by Mastodon. This behavior cannot be disabled through the admin interface. To force a single language for all new users, you must modify the server’s nginx or reverse proxy configuration to strip the Accept-Language header, but this is not recommended for multilingual instances.

Steps to Set the Default Language in the Admin Panel

1. Log in as an admin user
   Open your Mastodon instance URL and sign in with an account that has the Admin role. Only users with the Administrator role can access server settings.
2. Click the hamburger menu icon
   In the top-right corner of the Mastodon interface, click the three horizontal lines icon to open the side navigation menu.
3. Select Preferences
   From the side menu, click Preferences to open the user preferences panel.
4. Click Administration in the left sidebar
   In the Preferences page, locate the Administration section in the left navigation sidebar. Click Server Settings.
5. Open the Discovery tab
   In the Server Settings page, click the Discovery tab. This tab contains settings related to content discovery, federation, and default language.
6. Find the Default language field
   Scroll down to the Default language section. You will see a dropdown menu labeled Default language for new users. The current value is shown.
7. Select the desired language
   Click the dropdown and choose the language you want as the default for new users. For example, select English for the en locale.
8. Click Save changes
   Scroll to the bottom of the Discovery tab and click the blue Save changes button. A confirmation message appears at the top of the page.

Steps to Set the Default Language via Environment Variable

The environment variable DEFAULT_LANG overrides the admin panel setting. This method is useful for Docker deployments or when you want to enforce a specific language across all environments. The variable must be set before starting the Mastodon web and sidekiq processes.

1. Access your server terminal
   Connect to your Mastodon server via SSH or open the console for your hosting environment.
2. Open the Mastodon .env.production file
   Navigate to the Mastodon installation directory, typically /home/mastodon/live. Use a text editor such as nano to open the .env.production file: nano .env.production
3. Add the DEFAULT_LANG variable
   Add a new line at the end of the file: DEFAULT_LANG=en. Replace en with your desired locale code.
4. Save and close the file
   In nano, press Ctrl+X, then Y, then Enter to save changes.
5. Restart Mastodon services
   Run the following commands to restart the web and sidekiq processes:
   systemctl restart mastodon-web
systemctl restart mastodon-sidekiq
   For Docker deployments, restart the containers: docker-compose restart web sidekiq
6. Verify the change
   Open a private browsing window and navigate to your instance’s registration page. The interface should now display in the selected language. Register a test account to confirm the language is applied correctly.

Common Mistakes and Limitations

DEFAULT_LANG Environment Variable Not Taking Effect

If the DEFAULT_LANG variable does not change the language for new users, check that the variable is set before the Mastodon processes start. The variable must be present in the environment of both the web process and the sidekiq process. Restart both services after editing the .env.production file. Also verify that the locale code is correct. Mastodon ignores invalid codes without warning.

Existing Users Not Affected by Default Language Change

The default language setting only applies to users who register after the change. Existing users keep their current language setting. To change the language for all existing users, you must run a database migration or ask users to update their language in Preferences > Appearance > Language. Mastodon does not provide a bulk language update tool in the admin panel.

Registration Page Language Differs from User Interface Language

The registration page language is controlled by the DEFAULT_LANG environment variable or the browser language. The user interface language after registration is set based on the same priority chain. If you set DEFAULT_LANG to English but the registration page shows a different language, the browser Accept-Language header is likely overriding the setting. Use the environment variable method to enforce the language for the registration page.

Mastodon Admin Panel vs Environment Variable: Default Language Control

Item	Admin Panel Setting	Environment Variable DEFAULT_LANG
Configuration location	Admin > Server Settings > Discovery	.env.production file
Override by browser language	Yes, browser Accept-Language takes precedence	Yes, browser Accept-Language takes precedence
Affects registration page	No, registration page uses server locale or env variable	Yes, directly controls registration page language
Requires service restart	No, changes take effect immediately	Yes, must restart web and sidekiq processes
Applies to existing users	No	No

You can now set the default language for new users on your Mastodon instance using the admin panel for immediate changes or the DEFAULT_LANG environment variable for server-wide enforcement. After configuring the default language, test the registration flow with a new account in a private browser window. For advanced control, consider configuring the nginx proxy to modify the Accept-Language header for specific paths if you need to enforce a single language for all users.