hs.translation
ModuleTranslate text between languages using the macOS on-device Translation framework.
Language identifiers use BCP-47 format (e.g. "en", "fr", "zh-Hans").
Call hs.translation.supportedLanguages() to list every language the framework
recognises, and hs.translation.status() to check whether a specific pair is
installed and ready for offline use.
Language packs are downloaded through
System Settings → General → Language & Region → Translation Languages.
hs.translation cannot trigger downloads programmatically; session() returns
null when the requested pair is not yet installed.
Quick start
hs.translation.status("en", "fr").then(s => {
if (s === "installed") {
const session = hs.translation.session("en", "fr")
session.translate("Good morning").then(r => console.log(r))
} else {
console.log("Install en→fr in System Settings → Language & Region → Translation Languages")
}
})
Types
This module provides the following types:
Properties
This module has no properties.
Methods
hs.translation.supportedLanguages() -> Promise<string[]>
All language codes supported by the on-device translation engine.
Resolves to an array of BCP-47 identifiers (e.g. `["ar", "de", "en", "es", "fr"]`).
This covers every language the framework knows about, regardless of whether
the packs are installed locally. Use `status()` to distinguish installed
pairs from merely supported ones.
Declaration
hs.translation.supportedLanguages() -> Promise<string[]>Returns
Promise<string[]>
Resolves to an array of BCP-47 language code strings.
Example
hs.translation.supportedLanguages().then(langs => {
console.log(langs.includes("fr")) // true
})hs.translation.status(sourceLanguage, targetLanguage) -> Promise<string>
Check the installation status of a language pair.
Declaration
hs.translation.status(sourceLanguage, targetLanguage) -> Promise<string>Parameters
| Name | Type | Description |
|---|---|---|
| sourceLanguage | string | BCP-47 code of the source language (e.g. `"en"`). |
| targetLanguage | string | BCP-47 code of the target language (e.g. `"fr"`). |
Returns
Promise<string>
Resolves to `"installed"`, `"supported"`, or `"unsupported"`.
Example
hs.translation.status("en", "fr").then(s => console.log(s))
// "installed"hs.translation.session(sourceLanguage, targetLanguage) -> HSTranslationSession
Create a translation session for a language pair.
Returns an `HSTranslationSession`, or `null` if the system is running macOS
older than 26.0.
Declaration
hs.translation.session(sourceLanguage, targetLanguage) -> HSTranslationSessionParameters
| Name | Type | Description |
|---|---|---|
| sourceLanguage | string | BCP-47 code of the source language (e.g. `"en"`). |
| targetLanguage | string | BCP-47 code of the target language (e.g. `"fr"`). |
Returns
HSTranslationSession
An `HSTranslationSession`, or `null` on unsupported versions of macOS.
Example
const session = hs.translation.session("en", "fr")
if (session) {
session.translate("Hello").then(r => console.log(r))
} else {
console.log("Language pair not installed")
}