Current version: 0.3.1

Talk to me in fr-FR Talk to me in es-MX Talk to me in your user's native language

Talktalk is a JavaScript library for supporting translations for webpages. Its goal is to make it stupidly easy to support multiple languages seamlessly on one webpage.

You store each language's strings in a separate JSON file. Talktalk can either automatically replace HTML elements marked with data-talktalk (useful for static elements) or called in JavaScript via Talktalk.talk.

Talktalk also handles "special types" like dates, numbers, and other things supported in the Intl namespace.

Import talktalk.0.3.1.js via a <script> tag. Once loaded, it will read the user's device language(s) to get its sequence of preferred languages (e.g. ["en-US", "en"]). "en" will always appear as a fallback. It will look for files named talktalk/en-US.json and talktalk/en.json to associate "translation keys" with translated strings.

talktalk/en.json:

{
	"title": "Title of the webpage",
	"user": "User",
	"message": "Hello, #name!"
}

index.html:

<script src="talktalk/talktalk.0.3.1.js"></script>
<h1 data-talktalk="title"></h1>
<script>
	console.log(Talktalk.talk("message", {name: "world"}));
</script>

The above snippet demonstrates the two ways of getting translated text:

1. Any (non-script) element marked with a data-talktalk attribute will have its innerText set to a translated string. The data-talktalk content is the translation key.
2. Talktalk.talk(key) also performs a lookup and returns a string. If the translation string has replacement markers (e.g. "#name"), you can provide an object indicating what replacements to make (e.g. {name: "world"}). Here, "world" is a literal string, not another translation key. (You can nest Talktalk.talk calls if you really need it to perform another lookup.) It is also possible to pass numbers and some other data types as values in the replacement object; see "Using special types" section for full list.

If a translation isn't available for a higher-priority language, Talktalk will look at the lower-priority languages for a translation string. This is why a user with en-US only needs en.json to exist. However, if translations are only partially implemented for another language, the fallback text might be in literally a different language! (i.e. if es.json is missing a translation key, and it has to fallback to en.json)

Translation strings are usually just strings. If a translation string is actually an array, then each of the provided strings will be joined with the language's space character.

If a translation string is actually an object, this indicates a number-sensitive translation. The string must receive exactly one number as a replacement so it can determine which form to take.

"thingcount": {
	"singular": "There is #n thing.",
	"plural": "There are #n things."
}

In the above JSON, Talktalk.talk("thincount", {n: 1}) would yield "There is 1 thing." and Talktalk.talk("thincount", {n: 3}) would yield "There are 3 things.".

The keys for such an object may be the following:

• negative
• fractional
• zero/none
• one/singular
• two/dual
• few/paucal (only present in languages that have paucal forms!)
• many/plural
• other (always exists as a fallback)

In most languages, singular and plural are sufficient to cover all numbers (i.e. dual and paucal will always fall back to plural because it's a more general category). Note that in Arabic, the zero form is separate (in accordance with Intl.PluralRules's implementation).

Some amount of nesting of arrays and objects are allowed; at most, a translation string may be an array inside an object inside an array. This nesting is useful if a translation string contains several quantity-sensitive words:

"bookinginfo": [
	"You have booked",
	{
		"zero": "no rooms",
		"singular": "#rooms room",
		"plural": "#rooms rooms"
	},
	"for",
	{
		"zero": "no nights.",
		"singular": "#nights night.",
		"plural": "#nights nights."
	}
]

The above JSON mixes strings and objects into an array, which lets different parts of the sentence react to different numbers.

Translations can also be inserted after the fact with Talktalk.insertTranslations(lang, obj), where lang is the language and obj is an object containing translation key-value pairs.

When Talktalk.talk is handed a string, it converts it as a translation key. When handed something of any of the following classes, Talktalk handles the item accordingly. These types are simply handed off to an Intl formatter.

For Intl formatters that don't have corresponding types in vanilla JavaScript, I've included classes in Talktalk to represent them.

For all of the below special types, the settings are made to exactly mirror the settings available in the Intl formatter options. All fields are optional. These settings can either be provided in the replacement object (e.g. Talktalk.talk(5, {"number:minimumIntegerDigits": 2})) or directly in the language's JSON file. Unlike other translation keys, these settings won't accept fallback to different languages (e.g. a user with preferred language sequence ["es-MX", "es", "en"], when formatting a Date in Spanish, will only look for settings in es-MX.json and es.json. Format settings in en.json are ignored.)

Each Talktalk.* can be instantiated either as new Talktalk.NameOfSpecialType(...parameters) (normal constructor) or as Talktalk.nameOfSpecialType(...parameters) (function that calls constructor; avoids new keyword; is lowerCamelCase instead of UpperCamelCase).

When Talktalk is imported via a <script> element, the data-talktalk attribute will be read to determine the directory to look for all other resources. By default, this directory is talktalk. In addition to containing every language's JSON file, it can include settings.json which further configures Talktalk. It has the following fields:

• indicator (string, default "#x") shows how to mark replacements within strings. Must demonstrate on the label "x".
• fallbackLanguage (string, default "en") is the absolute last-resort language to check for translation strings.
• forceLanguageWithQueryParameter (string) If set, this string will be checked in the query parameters to set the language. In case you want to let clients pick a language in the URL (as opposed to just picking with navigator.language and navigator.languages)
• forceLanguage (string or array) If set, this language will be forced for all users with absolute highest priority! Why would you do this it defeats the purpose of Talktalk

When the user's primary language is written right-to-left (Arabic, Farsi, Urdu, Hebrew, etc.), document.dir is set to "rtl". This horizontally mirrors the design of the page.

Any styling which depends on the relative horizontal location of elements should be modified to adapt to RTL layouts; namely margin-left should become margin-inline-start, and margin-right should become margin-inline-end.

If LTR text is going to be contained in the middle of a RTL element/page, you can do one of two things:

• Mark the LTR element with dir="ltr" to make the entire element follow LTR rules.
• If the LTR text is sitting alongside RTL text, or you only want to work with strings, you can use Talktalk.wrapInDirectionalMarkers(text, originalLanguage) to make sure the inner text appears according to the directionality of originalLanguage. If directional markers aren't needed, this function just returns the text back.

Of course, vice versa for RTL text contained in LTR elements/pages.

Test your designs. RTL languages are difficult!

Most of the functions are intended for use within Talktalk. The functions I encourage to be used are:

• Talktalk.talk(item, replacements = {}), which translates keys or special types into the user's language
• The functions/constructors used to create the special type classes
• Talktalk.insertTranslations(lang, obj), which dynamically inserts new translations that don't appear in the JSON
• Talktalk.displayLanguage(), which gets the current display language (as an ISO-639 language code)
• Talktalk.fillElements(scope = document), which scans the pages for (non-script) elements with the data-talktalk attribute to perform translations without any replacements; is automatically called on page load
• Talktalk.wrapInQuotes(text, smart = true), which wraps the text in smart (or straight) quotes according to the user's language
• Talktalk.wrapInDirectionalMarkers(text, originalLanguage). If the user's language matches the writing direction of the text's originalLanguage, returns the text back. If the directions don't match, the text is wrapped in unicode directional markers to ensure the inner text appears correctly.