Skip to main content

Open Sourcing Grammaticus

Emily Du
Feb 26 - 3 min read

Regardless of how you use Salesforce, you have likely come across our Accounts, Contacts, Opportunities, or Cases tabs. We call these our standard objects and they make up a good part of our app. We often display these objects as part of a phrase, like “Create an Account” or “Create an Opportunity.”

One day, our founder walked into the office and said, “Rather than our customers having to adjust to our terms, we should adjust to their business needs and jargons.” So, engineers built a renaming feature which lets administrators change the name of standard parts of our product. Simple, right?

Not so fast. If you renamed “Account” to “Client” without changing anything else in the sentence, it would look both strange and grammatically incorrect: “Create an Client.” So you’ll probably end up writing a message like “a(n).” And that’s just for English! You can certainly imagine that this would get more complicated rapidly in other languages, where adjectives, cases/genders of nouns, etc. all vary.

We needed a mechanism that would allow a customer to rename our standard objects while ensuring that our UI text remained grammatically correct in all our supported languages.

Enter: Grammaticus, an open source grammar engine built in Java that allows users to rename nouns while keeping content grammatically correct. Grammaticus encodes the article, noun, and adjective declensions for over 50 languages, and supports programmatic use of nouns through the Renaming interface.

With Grammaticus, we use XML entities to represent the nouns, adjectives, and articles, such as “Create <a/> <Account/>” for the label above. Meanwhile, we have specific files to store the definitions for nouns, articles, and adjectives.

With this innovative approach to grammar-aware localization, we require engineers (and users who customize labels in their own org) to declare grammatical metadata about the parts of speech in their text (like adjectives, articles, and nouns), and we apply each language’s modifier rules for things like gender, declension, and more.

Salesforce also supports customers creating their own apps. Let’s say you want to add a separate object for “Partners” in addition to Contacts. You can create a custom object and name it Partners using Grammaticus. While engineers tend to avoid repetition and want to write a single message to cover multiple scenarios, in this case “Create a {0}” for example, it doesn’t always work so well with other languages. Grammaticus supports such use case through entity parameter and rewrites the UI message to “Create <a/> <entity entity=“0”/>”, allowing objects to be passed into the entity parameter <entity entity=“0”/> dynamically while ensuring grammar correctness. By doing this, Grammaticus prevents our application from feeling foreign and allows the expansion of our application to nouns defined by our customers.

Grammaticus not only helps our developers build language-appropriate UI messages, but also helps our translation teams tackle their work more easily, even when it comes to complex languages. In addition to prompting them to specify gender in their translation, and requiring a few other fields, the built-in label renderer allows the translator to display the strings in real-time as they would appear in the running software. This is hugely important as it allows the translators to see the previously translated names in context. It also allows them, if they are unsure about what case to add, for example, to check how a noun would be affected by the addition of a case.

We’ve been using Grammaticus internally for years and are excited that it’s now open sourced at for you to explore, implement, and contribute back to!

Grammaticus uses Maven for its build lifecycle. To get started, download the source code at and follow the wiki:

Related Open Source Articles

View all