Introduction
Welcome, developers! In this guide, we’ll delve into the core of Language Resolution in Empress, a feature essential to the customization and global accessibility of your Empress applications. As we navigate through this guide, you’ll learn how to effectively utilize and integrate this feature into your software development, enhancing flexibility and user experience.
The Basics of Language Resolution in Empress
Language resolution in Empress is predicated on the frappe.lang parameter. Its value determines the language for your session, resolved according to the following hierarchy:
- Form Dict > _lang
- Cookie > preferred_language (only for Guest Users)
- Request Header > Accept-Language (only for Guest Users)
- User document > language
- System Settings > language
Deep Dive into Language Resolution Methods
Form Dict: _lang
The _lang parameter within the Form Dict takes precedence. When set, it updates all translatable components within the given request. Empress leverages this mechanism in various places, including the handling of Email Templates and Print views.
# Example of setting language in form dict
frappe.form_dict._lang = 'ru'
Cookie: preferred_language
For a persistent yet temporary language setting, the preferred_language key can be set in cookies. This method allows for language persistence based on the client, utilized primarily for website language switcher functionality in Empress.
# Example of setting preferred language in cookies
frappe.session.cookie_manager.set_cookie("preferred_language", "ru")
Note: This method is only considered for Guest Users and is ignored for logged in users.
Request Header: Accept-Language
The Accept-Language header presents a cleaner, standard method for managing languages. If the previous two methods aren’t set, Empress begins resolving this header’s values, which represent an ordered set of acceptable languages specified by the client.
# Example of setting Accept-Language in request header
frappe.request.headers['Accept-Language'] = 'ru'
Note: This method is only considered for Guest Users and is ignored for logged in users.
User & System Settings
The language field in the User document sets the session language for a specific user, persisting across devices and clients. This allows users to view the website and Desk in their language of choice.
The language field in System Settings sets the site-wide language. It is the fallback language for all sessions, holding the lowest priority.
# Example of setting language in user document
frappe.db.set_value("User", frappe.session.user, "language", "ru")
# Example of setting language in system settings
frappe.db.set_value("System Settings", None, "language", "ru")
Conclusion
The Language Resolution in Empress feature is a critical component in the customization and global reach of your Empress applications. By understanding and implementing this feature, you can provide a tailored user experience, catering to diverse user preferences and ensuring your application’s accessibility on a global scale. This guide provides an in-depth guide into the various methods of language resolution, empowering you to integrate this feature effectively into your software development and customization.