Password Pusher provides support for 30+ languages, allowing you to easily adapt your application to a global audience. The application automatically detects and serves content in the user’s preferred language.

Overview

Password Pusher uses automatic language detection to provide the best experience for your users. The language selection happens automatically based on several factors, with no configuration required for basic operation.

Key Features:

  • Automatic language detection from browser settings
  • User account language preferences
  • URL parameter override for specific links
  • Configurable default language
  • Ability to limit available languages

Supported Languages

Password Pusher supports the following languages (34 language codes):

Code Language Code Language
ca Català lv Latviski
cs Čeština nl Nederlands
cy Cymraeg no Norsk
da Dansk pl Polski
de Deutsch pt-BR Português (Brazil)
en English pt-PT Português (Portugal)
en-GB English (UK) ro Română
es Español ru Русский
eu Euskara sr Српски
fi Suomi sk Slovenský
fr Français sv Svenska
ga Gaeilge th ไทย
hi हिन्दी uk Українська
hu Magyar ur اردو
id Indonesian zh-CN 中文
is Íslenska    
it Italiano    
ja 日本語    
ko 한국어    

Default Language: English (en)

Language Selection Priority

Password Pusher uses a priority-based system to determine which language to display. The system checks these sources in order, using the first match found:

1. URL Parameter (Highest Priority)

If a ?locale=<code> parameter is present in the URL, Password Pusher will use that language setting.

Example:

https://pwpush.example.com/p/abc123?locale=fr

This forces the page to display in French, regardless of other settings.

Use cases:

  • Sharing pushes with specific language requirements
  • Testing language translations
  • Overriding automatic detection

2. User Account Preference

If a user is logged in and has set a preferred language in their account settings, that language will be used.

Note: This only applies to logged-in users. Anonymous users will use other detection methods.

3. Browser Language (HTTP_ACCEPT_LANGUAGE)

Password Pusher checks the Accept-Language HTTP header sent by the user’s browser. This header reflects the language preferences set in the browser or operating system.

How it works:

  • Browser sends language preferences (e.g., Accept-Language: fr-FR,fr;q=0.9,en;q=0.8)
  • Password Pusher matches the best available language
  • Falls back to next preference if exact match not available

Note: This is the most common method for anonymous users and provides automatic localization without any user action.

4. Default Language (Fallback)

If none of the above methods provide a language, Password Pusher falls back to the configured default language (English by default).

Configuration: See Setting the Default Language below.

User Account Language Preferences

Logged-in users can set their preferred language, which will be used for all their sessions.

Setting User Language Preference

  1. Navigate to “Edit Login Details” from the user menu
  2. Find the “Preferred Language” dropdown
  3. Select your desired language
  4. Save your changes

The selected language will be used for all future sessions until changed.

Note: This preference only applies when the user is logged in. Anonymous users will use browser language detection or the default language.

Setting the Default Language

You can configure a default language for your Password Pusher instance. This language will be used when:

  • No URL parameter is provided
  • User is not logged in (or has no preference set)
  • Browser language cannot be determined or is not supported

Important: The default locale must be in the list of enabled languages. If you disable a language that is set as default, the application will fall back to English.

Set the PWP__DEFAULT_LOCALE environment variable:

Docker Compose:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    environment:
      PWP__DEFAULT_LOCALE: 'fr'  # French

Docker Run:

docker run -e PWP__DEFAULT_LOCALE='fr' pglombardo/pwpush:stable

Shell:

export PWP__DEFAULT_LOCALE='fr'

Method 2: settings.yml File

Add or update the default_locale setting in your settings.yml file:

default_locale: fr

Examples:

  • PWP__DEFAULT_LOCALE='es' - Spanish
  • PWP__DEFAULT_LOCALE='de' - German
  • PWP__DEFAULT_LOCALE='ja' - Japanese
  • PWP__DEFAULT_LOCALE='zh-CN' - Chinese (Simplified)

Note: Use the language code (e.g., fr, es, de) not the full language name.

Limiting Available Languages

You can restrict which languages are available in your Password Pusher instance by configuring the enabled_language_codes setting. This is useful when you:

  • Only serve specific regions
  • Want to simplify the language selector
  • Need to comply with organizational requirements

Configuration

Method 1: settings.yml File

Modify the enabled_language_codes list in your settings.yml file:

enabled_language_codes:
  - en    # English
  - fr    # Français
  - de    # Deutsch
  - es    # Español

Example: European Languages Only

enabled_language_codes:
  - en    # English
  - fr    # Français
  - de    # Deutsch
  - es    # Español
  - it    # Italiano
  - nl    # Nederlands
  - pl    # Polski

Example: Asian Languages Only

enabled_language_codes:
  - en    # English
  - ja    # 日本語
  - ko    # 한국어
  - zh-CN # 中文
  - th    # ไทย
  - hi    # हिन्दी

Method 2: Environment Variable

Currently, language codes must be configured via settings.yml. Environment variable support may be added in the future.

Important Considerations

Default Language: Ensure your default language (PWP__DEFAULT_LOCALE) is included in the enabled_language_codes list. If not, the application will fall back to English.

User Preferences: If a user has a preferred language that is later disabled, they will see the default language or their browser’s language (if enabled).

URL Parameters: Users can still use ?locale=<code> to request a language, but if that language is disabled, it will fall back to the default or browser language.

Note: Disabling languages affects all users and all parts of the application, including the language selector dropdown.

Examples

Example 1: French-Speaking Organization

For an organization serving primarily French-speaking users:

# settings.yml
default_locale: fr
enabled_language_codes:
  - fr    # Français
  - en    # English (as fallback)

Docker Compose:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    environment:
      PWP__DEFAULT_LOCALE: 'fr'
    # Mount custom settings.yml with enabled_language_codes

Example 2: Multi-Regional Deployment

For a deployment serving multiple regions:

# settings.yml
default_locale: en
enabled_language_codes:
  - en    # English
  - es    # Español
  - pt-BR # Português (Brazil)
  - fr    # Français

Example 3: URL Parameter Override

Share a push with a specific language:

https://pwpush.example.com/p/abc123?locale=ja

This will display the push page in Japanese, regardless of the user’s browser or account settings.

Troubleshooting

Language Not Changing

Issue: Language doesn’t change when expected.

Solutions:

  1. Check URL parameter: Ensure ?locale=<code> uses a valid language code
  2. Verify enabled languages: Confirm the language is in enabled_language_codes
  3. Clear browser cache: Cached language preferences may persist
  4. Check user preference: Logged-in users’ preferences override other settings

Default Language Not Working

Issue: Default language setting is ignored.

Solutions:

  1. Verify language code: Use correct code (e.g., fr, not french)
  2. Check enabled languages: Default language must be in enabled_language_codes
  3. Restart application: Changes to settings.yml require a restart
  4. Check environment variable: Ensure PWP__DEFAULT_LOCALE is set correctly

Language Selector Missing Languages

Issue: Expected languages don’t appear in the language selector.

Solutions:

  1. Check enabled_language_codes: Only languages in this list appear
  2. Verify configuration: Ensure settings.yml is properly loaded
  3. Restart application: Configuration changes require a restart

See Also

Updated: