This is a case study on improving the readability of an internal corporate email. I focus on high-level factors such as organization and audience rather than small details like formatting and diction.

In software development, internationalization is a complex process, and it starts with translating the text of the application. Text labels are called strings.

To translate strings, a software development team typically outsources them to a translation company, which is a process fraught with back-and-forth between customers and product development.

New strings and revisions must be funneled to the localization team, who is responsible for requesting quotes from translation vendors. The localization team sends out a reminder email to other teams, hoping to collect the latest and greatest updates.

Ah, the smell of shiny new strings.

Other teams have difficulty filling out the collection forms. They’d leave out crucial info like identifier keys for each string. This suggests that non-technical managers are unaware of the reason for unique keys, and they assume that providing the English string is enough.

We want to provide teams a clear set of expectations and guidelines for localization.

Here is an abridged version of the original email:

Reminder: String Freeze #

ATTENTION: String Freeze for Release V

Dear teams,

The deadline for our string freeze for Release V is coming next week DD, MMM, end of day UTC.

CSV-based strings

• @LocalizationTeam collects CSVs from Git repositories that are registered with us.
• If you need any other CSV to be considered, please mention in the [Link to wiki page].
• Also, mail @Name and @LocalizationTeam

Non CSV-based repositories: Any strings from Firebase, backend DB, Azure CosmoDB, share them with us @LocalizationTeam in [this spreadsheet]. If you have trouble accessing the file, let me know in the chat.

Screenshots: (explanation of why screenshots are helpful for translators, as well as how to name them). Upload your screenshots to [Link to drive] If you have multiple screenshots, put them in PowerPoint slides and name the slide with TEAM-PRODUCT-RELEASE-V-DATE.pptx.

Useful links and pointers about our Localization Process

1. CSV

   • (repeats information about how we collect CSVs from Git repositories, and to contact us about CSV repositories so we can track them)

2. Database

   • Please inform us about database strings.
   • Use this format:

   Product	Source database	Row Key	English text	Context about the string

3. Shared Data

   • Please use this format when sharing strings.

4. Application Data

   • Please share your strings thru email.

5. System Notifications

   • ATTN Product managers, please share UI strings so the technical writing team can review. Also send another email to @LozalizationTeam before the freeze date.

Guidelines for introducing UI strings

1. Does the string already exist? Reuse them.
2. Is the row key a duplicate? Can something be reused from our existing CSV translations?
3. Is the string a partial string (a fragment string that only has meaning after being rendered with data)? Please provide @LocalizationTeam with context about the string.
4. Ensure not to have split strings (broken sentences typically used to recombine or render them in a special matter).
5. Proofread string (value) for spelling and grammar.
6. Vigilance with symbols being part of string-like, such as quotes, $ @ # ! ~ % & *
7. Let us know if there is a CSV file not on our list.

Thanks and regards,
LocalizationTeam

I’ve simplified some of the paragraphs. The original message was much longer! It was written by someone who was too busy to make it user friendly. The dates and links that change for every release are placed together for easy access… It was written for the convenience of the original author, who spearheaded a burgeoning localization team.

Evaluating the message #

I will break down each part of the email and explain my thought process.

The Introduction #

Reminder - String Freeze

ATTENTION: String Freeze for Release V.

Dear teams,

The deadline for our string freeze for Release V is coming next week DD, MMM, end of day UTC.

Lack of Purpose
The email does not explain what a “string freeze” is. In corporate jargon, a “freeze” is commonly known as a promised date, an Estimate Time of Arrival (ETA), for when a task can be completed.

The localization team has to send out work to the translation company; they can’t wait around forever. Great, but every team has work and deadlines. What is this deadline for?

The fix: add a sentence about the purpose of the reminder. “This is your chance to request localization from the LocalizationTeam.” It’s a call to action and informs the reader of an opportunity.

The Middle #

Right off the bat, the next topic is about the formatting of the strings.

CSV-based strings

• @LocalizationTeam collects CSVs from Git repositories that are registered with us.
• If you need any other CSV to be considered, please mention that at [Link].
• Also, mail @Name and @LocalizationTeam

Non CSV-based repositories: Any strings from Firebase, backend DB, Azure CosmoDB, share them with us @LocalizationTeam in [this spreadsheet]. If you have trouble accessing the file, let me know in the chat.

However, the heading is ineffective. Comma Separated Values (CSV) is a file type, not a process or a task. Also, strings cannot be CSV-based. Well, okay, they can be, but I will explain why that trait is not relevant for this email.

If we simplify the message, it is saying:

CSVs
We love CSV file format. Developers, it’s better if you store your strings in CSV and give us the GitHub link to it.

If you store strings in a database, then you’ll have to follow our tedious submission process.

There are CSV strings and not-CSV strings. Two simple categories, right? If we follow the mutually exclusive and collectively exhaustive (MECE) principle, the distinction seems to work.

The email states a few examples of “non-CSV” strings, like database strings.

In practice, all strings are implemented in a database eventually. Database performance matters to a developer.

In practice, corporate business professionals work with one format: spreadsheets. Only CSV matters to a translator.

In practice, strings are both CSV and database-“based.” CSV and non-CSV are not mutually exclusive categories. Hence, the heading doesn’t make sense in the current context.

In the past, the distinction between CSV and database strings might’ve made sense, when the applications and projects were structured differently. However, it doesn’t make sense when you consider the human behind the work. Regardless of what format the strings are in, they need to be reviewed and translated. We should prioritize what the translators want, which is a CSV.

We find the same problem in the next part:

Useful links and pointers about our Localization Process

1. CSV

   • (repeats information about the CSV repositories)

2. Database

   • Please inform us about database strings.
   • Use this format…

3. Shared Data

   • Please use this format when sharing strings.

4. Application Data

   • Please share your strings thru email.

5. System Notifications

   • ATTN Product managers, please share UI strings so the technical writing team can review. Also send a different email to @LozalizationTeam before the freeze date.

Unnecessary Repetition
There’s a lot of verbose policy stitched together. The points are not distinct enough from each other. Each point amounts to the same action item: GIVE US YOUR STRINGS FOR REVIEW.

From a localization standpoint, there is no difference between Shared Data, Application Data, or System Notification Strings. Yes, the translator needs the context in which the string will appear, but the categories do not affect the localization manager’s work, the process of collating new strings into batches before sending them out for translation.

We can axe these points and just have one process for all.

No matter if your strings are stored as CSV or not, the tedious submission process is the same. The strings need to be extracted into a translator-friendly CSV format, supplemented with screenshots and context, proofread by technical writers, and filled out by the translation vendor.

I was inspired by the Call for Submission Guidelines for Apex Magazine. Since our string freeze reminder is the same as a call for submissions, we can use the same structure.

The Ending #

The last part, the guidelines, are hidden at the bottom.

Guidelines for introducing UI strings

1. Does the string already exist? Reuse them
2. Is the row key a duplicate? Can something be reused from our existing CSV translations?
3. Is the string a partial string (a fragment string that only has meaning after being rendered with data)? Please provide @LocalizationTeam with context about the string.
4. Ensure not to have split strings (broken sentences typically used to recombine or render them in a special matter)
5. Proofread string (value) for spelling and grammar
6. Vigilance with symbols being part of string-like, such as quotes, $ @ # ! ~ % & *
7. Let us know if there is a CSV file not on our list.

The guidelines are mixed between formatting and process concerns, so it would be best to separate them.

For example, guidelines 1, 2, and 5 are prerequisites before anyone submits anything, and should go near the beginning of the email.

3, 4, and 6 are very similar. Partial strings are a headache for translators who need the full sentence for an accurate translation. Random punctuation is indicative of variables, but they can also be there on purpose. The engineering team should be aware of these guidelines before implementation, and try not to split strings unless needed.

7 is a repeat about how the localization team wants your CSVs.

Mixed Audience
The recipients of the email includes everyone in product development. Although the reminder is mainly aimed at product managers, some of the guidelines include constraints that the engineering team needs to know.

Many product managers want to have their products localized, but it’s not clear how. So, let’s make it easy for them to follow.

These are the elements we need in our new email:

• Desired Format
• Submission Guidelines
• Constraints and Limitations

Results #

After evaluating the main message and the purpose of the email, I can craft a revised version that is much clearer about its purpose.

The revised email:

String Freeze for Release V #

Dear Teams,

The String Freeze Deadline for Release V is coming MMM DD at end of day UTC.
This is your chance to request localization from the LocalizationTeam.

New String Submissions #

To submit strings for translation:

1. Before submitting, check for reuse and RowKey conflicts.

   • Does the English string already exist in [L10N CSV]? Consider reusing the string if the context is similar.
   • Is the RowKey already present in [L10N CSV]? Please do a diligent review to avoid RowKey conflicts.
   • If existing strings need revision, then submit an email to @LocalizationTeam.
   • RowKeys are MANDATORY, we will not translate strings without RowKeys provided. We use RowKey+English text to check for uniqueness.

2. Format strings according to guidelines (see next section).

3. Add new strings to this spreadsheet: [String Collection]

   • If you can’t populate or access the file, please let us know asap per email or chat!

4. Provide supporting screenshots. Screenshots help the translators understand the application.

   • Please place screenshots into [Screenshots Collection]
   • For multiple screenshots, put them in PowerPoint slides and name the slide as PRODUCT-RELEASE-V-DATE.pptx

Formatting Guidelines #

In the submission spreadsheet, our header format is:

Product	Source database	RowKey	English string	Context about the string
Your team	Database where the string is stored	Identifier key	Text in english	How the string renders in the application

English String

We heavily discourage split strings (sentences which are intentionally broken to multiple parts present at UI in a special manner).

• We translate on a sentence-by-sentence basis to preserve the meaning.
• Provide the entire sentence with variable placeholders. For example:
  • We found %d results for “%s”:
  • The following file types are not allowed: %s

Context About the String

To fill out this column, consider:

• Is the string a partial string that gets its complete meaning when rendered with data?
• Specify if symbols and punctuation (“”, ‘’, $, @, !, ~, %, &, *) are variables or part of the string.
• Field names or product names which are proper nouns.

Examples:

English string	Context about the string
How would you like to create your #Type?	#Type is a variable
Select code	Select is a verb, numbers are chosen from a list

File Format #

We prefer CSV files because we keep track of Git CSV repositories and pull the deltas automatically: [Localization Tracker].

If your repo is not included in the Localization Tracker, email @Contact or @LocalizationTeam to add or retire CSV repositories.

Scope #

We generally do not localize custom client strings. Submitted strings should be for our generic product offerings.

*Exceptions apply, such as a contractual agreement with a client.

Thank you for your cooperation,
LocalizationTeam

In the revised email, I emphasize the submission process, and provide real examples of confusing strings and how to address pitfalls. The email has gotten longer, which seems contrary to most advice about writing shorter emails. In our case, the managers have a vested interest because localization is often a requirement. Proper headings and introductory clauses help them scan the email.

Maintenance and old processes are still explained in the File Format section. The localization team can only promise to maintain our own repositories. Whatever is stored in databases is up to the developers.

I also include a note about scope. Typically, the localization team doesn’t translate bespoke features, except for a few legacy contracts. Going forward, the company wants to avoid this obligation.

Email is not the most searchable or discoverable format. Should these submission guidelines be put into a Word document or shared on a wiki? If the email reduces the amount of incomplete submissions, I think it does its job. Eventually, I would like to have a dedicated document so that the knowledge will not disappear. Strategies for retaining and syndicating knowledge can be discussed at a later time.