Field-level vs entry-level localization

Hello Navigators! 👋

The world of content management systems (CMS) is replete with inscrutible plain English. CMS documentation and other modern tools presents us with combinations of words that, each taken alone, are easy to understand. But once they are strung together to describe a feature or function, they form concepts that are hard to grasp.

'Field-level localization' and 'entry-level localization' rank high in this category.

These two expressions refer to localization methods, each with its own virtues: flexibility, granularity, governance, customizability.

What are they? Why would you use one over the other?

The answers depend on how you plan to manage your localization program. In this article, I explore these two concepts modelled on Contentful (www.contentful.com).

Definitions of 'Field' and 'Entry'

Contentful defines the component parts of its system in this article: Structured content & content models (requires registration, but is free of charge). I cite the definitions of 'field' and 'entry' from that article below:

"Fields (aka attributes) represents different properties or characteristics for a piece of content. Your development team will decide which fields to include and what data types to assign each field (text, rich text, number, date, location, media, boolean, JSON object, or reference)." -Contentful.com

You have full control over what the container will do. Design fields for an ecommerce site, a web form, a registration page for an event. Whatever you want. (Visit the Field Types page in Contentful for a comprehensive list.)

• Create a title field that accepts only 50 characters,
• Create a short description field that accepts up to 1,000 characters and that can be formatted as rich text.
• Create a numbers field that accepts integers as user input.

"An Entry is a piece of content based on a content type. You might think of an entry as an "instance" of that content type. You might have hundreds or thousands of entries based on a single content type. As a content author, you will be creating many entries." - Contentful.com

Entries are assemblages of fields that display as a webpage to the end user. They give the impression of a single, contiguous page of content, like a Word doc. But behind the scenes, the entry is pulling different fields associated with it under the content type from the content model.

In pictures

Here's what the 'title' field configuration page looks like in a few screenshots. Although the aim of a field may be simple—configure a title field that accepts up to 50 characters (marked in red)—there are many ways to control the field. So many, in fact, that Contentful subdivides the configuration page into chapters (marked in blue)!

What is most relevant to us is the 'Enable localization of this field' setting that appears towards the top of the page. This is what makes the field visible to the given translation app available on the Contentful Marketplace.

Entries, on the other hand, comprise multiple fields—could be two, could be 40—strung together to create a webpage.

The screenshots below are taken from pre-configured content available to new Contentful users when signing up for an account. This entry appears under the content type 'Course' and is titled 'Hello SDKs'. Field properties and validation settings are shown for each one.

• 'Title': Required, en-us, max 256 characters.
• 'Slug': Required.
• 'Image': Required.
• 'Short Description': Required, en-us, max 256 characters.
• And so on.

On-Platform Translation

Before deciding which approach to use, you have options about how to translate your content.

One is the out-of-the-box editor available in Contentful. Permissioned users can log in and translate directly in the system. Contentful has done a nice job making the UI spacious and intuitive, so it's not a bad environment for thinking and writing.

But, the drawback to this approach is that Contentful is not a CAT tool. No translation memory or glossary is attached and syncing with the latest translation performed in the editor (as of this writing). That makes consistency and efficiency a challenge.

Exporting for Translation

So, the more common case is to extract entries into a file format and export them (often json, but depending on the app, could be csv, xml, etc.). You can use an app to send files to a language service provider (LSP) for human translation or MTPE, or route them to a wide variety of automated services via workflow automation like www.blackbird.io.

In the json example below:

• The nested keys under 'content' need translating.
• The parent-level keys are system data that need to remain in English.

{
 "source": "en-US",
 "target": "de-DE",
 "entryId": "34MlmiuMgU8wKCOOIkAuMy",
 "contentType": "course",
 "wordCount": 35,
 "nameForFile": "hello-sdks-34Ml",
 "content": {
  "title": "Hello SDKs",
  "shortDescription": "Learn about best practices when using our SDKs.",
  "description": "By looking at the code of the example app, you'll get a sense of how to use a Contentful SDK in your favorite programming language."
 },
 "type": "Entry"
}

In my testing, I've found that the data structure of a field-level or entry-level request is largely the same when expressed in key/value pairs.

The field-level and entry-level methods result in the same data structure because the differences in how Contentful handles them are abstracted away (i.e., handled internally) when generating the JSON export. Though, there may be some differences between one app and another as to how the keys are generated.

Which One Is Right For You?

With all of that in mind, let's turn to a series of Q&A to demonstrate how each method differs. I'm going to assume that you will export your content for localization.

1. I want to develop and maintain a translation memory in my CAT tool or TMS. Will it make a difference if I select field-level or entry-level localization?

No. Most apps generate a json file format with a mix of system keys and keys requiring translation. Have your localization engineers develop a file filter in your CAT/TMS environment, and translatable content will be exposed therein. The data can then be saved to a translation memory as usual.

2. I have colleagues who are SMEs in the target locales. I am setting up a localization program and will ask them to do quality reviews. Is one method better than the other in this case?

It depends. There are notable differences between field-level and entry-level localization in this regard.

The field-level approach allows for strong governance. You can limit the role and associated permissions of your colleagues so that they can only access entries in their language of expertise. This helps to prevent human error.

With field-level, you can also set up fallback settings in the case of empty fields. In effect, this means that if one translation is completed earlier than another, you can publish it while waiting for the other.

Keep in mind, though, that the field-level approach ties all the fields together on the back end. If one of the locales is unpublished, it will unpublish all of them. Please see here for more details.

On the other hand, the entry-level approach is best if asynchronous publishing is the norm because, for instance, your company routinely pushes updates to one priority locale more quickly than others.

With entry-level, locales are independent of one another. You can keep a published version of German online even if you unpublish other corresponding locales.

But granular user permissions are not available in entry-level. It's a tradeoff.

3. I want to create custom content in the target locale. Which is better for this purpose?

The entry-level approach is a little better, but neither is perfect.

Behind each individual field is a host of settings that have been pre-configured in the content model (see screenshots above). It is difficult to stray too far beyond the boundaries of those settings. Although, there can be some leeway in certain individual fields, eg a rich-text body field.

With entry-level localization, localized entries are linked references. One locale won't impact another because it is an independent entity in the system.

Let's say you are publishing blog entries. You could put all your content into a single rich-text field and then transcreate it however you wish.

At the end of the day, though, entry-level also relies on fields, which might restrict how you'd like to customize your content.

This question comes up often and I recently read that there might be yet another approach: content-type localization. I'm investigating this now and will share my findings in a future article.

4. How should I get started?

If you are working with an LSP, they should have a technical person available to walk you through how everything works. I recommend pseudo-translation testing with real data before submitting real translation orders.

Conclusion

This article addressed two localization methods available in Contentful: field-level and entry-level localization.

I started the article by mentioning what I consider a "paradox of plain English" in the realm of CMSs and modern technology. Jargon-less descriptions of features and functions that are, nevertheless, difficult to understand. And that pose a potential a barrier to entry (no pun intended 😇).

I defined key concepts and then illustrated them through a combination of pictures and words in this article, with the goal of breaking down that barrier to some degree.

The choice of which method to use should be made upstream when architecting your web app or website. Please don't wait until all the content is done before starting to think about how to localize it.

Incidentally, other headless CMSs like Sanity, Contentstack, Storyblok operate along similar lines. The verbiage they use to describe their features varies, but how the functions operate are strikingly similar. More to come on that front.