Localize authentication for MongoDB App Services & Realm

Richard Krueger
5 min readAug 14, 2023


To have another language is to possess a second soul. — Emperor Charlemagne

Cosync JWT stands as an open source authentication solution meticulously crafted for integration with mobile applications constructed atop MongoDB App Services and the Realm real-time database. A standout benefit of Cosync JWT is its self-hosted nature, functioning within the developer’s infrastructure stack rather than relying on an external third-party SaaS offering. In a unique approach, Cosync doesn’t levy charges based on the user count of an application; instead, there exists a fixed monthly cost per developer seat to access the comprehensive Cosync administration tools catering to authentication services.

When pondering authentication services, the notion of multi-language localization support might not be an immediate consideration. After all, authentication primarily involves confirming a user’s identity and credentials — a concept not inherently associated with localized user interfaces. Nonetheless, the Cosync JWT authentication service does encompass messaging, defaulting to English, that should be translated to the user’s specific locale when necessary. This messaging commonly applies to the subsequent scenarios:

  • Email confirmation during signup via a 6-digit code
  • Email verification during signup via a hyperlink
  • Click-through page for email verification via a link
  • Password reset notification email
  • Invitation for onboarding via email
  • Email containing QR verification for Google Authenticator
  • SMS message configured for phone-based 2FA login

Localizing the programmatic user interface is traditionally managed through the tools offered by the programming framework itself. This could encompass Swift for iOS, Kotlin for Android, or even React Native for cross-platform development. However, when dealing with authentication, which is distinctively managed by an authentication server (in the context of Cosync JWT, a self-hosted Node.JS process operating on a developer server), the localization of messaging doesn’t fall within the scope of the application programming framework.

Hence, the responsibility falls on the developer who aims to implement application localization across multiple languages to thoroughly comprehend the methodology governing the localization of authentication messaging.

The Cosync JWT authentication system, accessible through its portal found here, offers a feature known as Email Templates. Initially, all these templates are furnished in English by default, which can be perfectly suitable during the initial phases of application development and possibly even for the product’s initial launch. Nonetheless, as the application gains momentum and attains success, the requirement for translation into other languages frequently emerges. This translation endeavor encompasses not solely the product’s user interface screens, whether on iOS or Android, but further extends to encompass emails and SMS messages disseminated to users by the authentication system.

To facilitate template localization, the Cosync JWT authentication system introduced the concept of a locale, represented by a two-letter code that corresponds to a supported language. The list of locales supported by Cosync JWT is provided below. Each registered user operates within a designated locale, which is established during their application onboarding process, whether through signup or registration in response to an invitation. Importantly, users have the flexibility to modify this locale at a later point if needed.

An application established within the Cosync JWT authentication system has the capability to incorporate additional locales it wishes to accommodate, along with the ability to tailor the messaging within these locales. It’s important to note that an application user is restricted to choosing their locale from the subset of locales that the application supports. By default, the sole supported locale is EN, which represents English.

Setting up Locales

Incorporating a new locale into an application is a straightforward process within the Cosync JWT authentication system. To initiate this, navigate to any template within the Email Templates tab of the application settings. From there, click on the option labeled EDIT LOCALE.

Adding a New Locale to an Application

This action will open a dialog box, enabling you to introduce a new locale for the application. To achieve this, simply click on the Add Locale button provided.

Bring up Modify App Locale dialog box

This action will prompt a menu to appear, offering you the option to choose the new locale you wish to add, such as FR (for French), for example. The Cosync JWT authentication system supports the ISO 631–1 codes that are described here ISO 639–1 codes

Select locale (e.g. ‘FR’ — French) to add

Upon selecting a new locale to incorporate, you will observe its addition to the roster of supported locales for your application. It’s worth noting that the default locale EN (English) remains unremovable.

Click Submit to save new locale to application

When a new locale is introduced, like FR for French, the messaging content will initially remain in English. The responsibility falls upon the developer to undertake the translation of this messaging into the newly added locale. As an illustration, the translated text for the Password Reset template in French would read as follows:

Edit localization text for ‘FR’ — French locale

In the event that an application user has their locale set to FR (French), they would receive the French edition of the Password Reset email upon requesting a password change. As evidenced, the Cosync JWT authentication system streamlines the implementation of localization support.

In summary, the Cosync JWT authentication system offers an array of localization functionalities that aid developers in accommodating a diverse array of languages for their applications. This software is open source and ensures a cost-effective solution for development endeavors. We trust you found this informative, and to delve deeper into the world of Cosync, feel free to explore more at our official website here.



Richard Krueger

I have been a tech raconteur and software programmer for the past 25 years and an iOS enthusiast for the last eight years. I am the founder of Cosync, Inc.