Organizations that are new to ActionKit can run into questions about the various elements involved in translating their forms into multiple languages.
The terminology here can be confusing, with words like “page” and “template” being used to mean different things depending on the context, so I thought it might be useful to review the major data structures involved in form translation to see how they fit together.
Pages
In ActionKit, the page is the central unit of content, containing all of the information about an advocacy opportunity, donation form, unsubscribe tool, or other way that users can engage. In the ActionKit database, that page has associated fields that hold both user-visible content (such as the text of a petition or the “thanks for signing” text shown after a user completes it) as well as internal metadata that governs how the page functions.
When a user fills out one of those forms, that fact is recorded as an action, along with any values entered in the form fields and metadata like timestamps.
Templatesets and Templates
Under the hood, the appearance and functionality of each page is governed by the templateset it is associated with. A templateset contains a group of named template files containing Django tags, HTML, CSS, and JavaScript.
There are just over a dozen page types — petition, survey, donation, unsubscribe, etc — and each one has a corresponding template file that controls the layout of pages of that type.
Organizations can define multiple templatesets to be used for different groups of pages — for example, an organization that has separate branding for North American and European audiences might set up two templatesets, each of which reflects those identities, including different stylesheets, page layouts, and navigation links.
In other cases, a single templateset can use page metadata to produce multiple results — for example, an organization that has separate chapters in each US state might define a custom page field to store the associated state chapter, and then the the templateset could use Django template tags to insert the appropriate chapter’s name and logo when rendering that page.
Languages
To handle translations, each page can specify a language. (ActionKit provides basic translation text for a few languages, but organizations can add as many as they would like.) Each language has an associated translation table that maps English phrases to the corresponding equivalent in that language. These phrases can then be used in the markup contained in a templateset, and whenever a page is rendered they will be replaced by the equivalents in that page’s language. Some phrases are needed to translate built-in portions of the ActionKit interface, such as the label for the standard email-address field, while others may be added; for example, if an organization wants to include a “Learn More About Us” link at the top of every screen, this phrase can be added to the translation tables so that users viewing a French petition will see the equivalent phrase in that language.
Multilingual Campaigns
Pages which are translated equivalents of each other, such as a single petition available in several languages, can be grouped together as a multilingual campaign. Users who arrive at one page in this group can be offered a menu or links to let them switch to the equivalent page in a different language, and reports can easily sum up the total number of actions across all of the different language-specific versions.
Cardinality and Lifecycle
Generally speaking, an organization is likely to only have a few templatesets, and a handful of languages. Setting these up can be a detailed process, but they generally don’t change very often — most of the effort here will happen during the initial migration to ActionKit, or over time when page layouts are refreshed or new features are added to the site.
Pages (and multilingual campaigns) are added more often, with some organizations creating multiple new pages every week. Old pages may be deactivated when an advocacy campaign has reached its conclusion, but they’re not completely deleted, so over time even a small organization can wind up with hundreds of pages and large ones can have thousands.
By comparison, the user and action records are much more numerous and frequently updated — it’s not unusual for an ActionKit instance to contain millions of user records and hundreds of millions of actions.
Leave a Reply