Crate translation 

translation-rs

Safe Rust bindings for Apple’s Translation.framework on macOS, plus typed language helpers for canonical language identifiers, language pairs, translation configuration state, translation responses, translation errors, and NaturalLanguage-backed language recognition.

Status: v0.3.0 covers all public Translation.framework symbols in the current macOS SDK and adds a Tier-1 async_api module for Future-based translation and availability workflows.

Quick start

use translation::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = Language::new("en").canonicalized()?;
    let target = Language::new("es").canonicalized()?;
    let pair = LanguagePair::between(source.clone(), target.clone()).canonicalized()?;

    let availability = LanguageAvailability::new()?;
    println!(
        "{pair:?} status: {:?}",
        availability.status_for_language_pair(&pair)?
    );

    let mut configuration = TranslationConfiguration::new()
        .with_source(source)
        .with_target(target);
    configuration.invalidate();

    let session = TranslationSession::from_translation_configuration(&configuration)?;
    match session.translate("hello world") {
        Ok(response) => println!("{}", response.target_text()),
        Err(error) => println!("translation unavailable: {error}"),
    }

    println!("recognized: {:?}", recognize_language("hello world")?);
    Ok(())
}

Highlights

• Language and LanguagePair wrappers that canonicalize Locale.Language identifiers through the Swift bridge.
• LanguageAvailability access to supportedLanguages, pair status, and text status, including optional target-language queries.
• TranslationConfiguration for mutable source/target configuration state and invalidation version tracking.
• TranslationSession with can_request_downloads, is_ready, cancel, eager batch translation, and streaming translate(batch:) iteration.
• TranslationRequest setters plus TranslationResponse constructors, serde support, and typed language accessors.
• TranslationError variants that preserve both errorDescription and failureReason from Translation.framework errors.
• recognize_language / detect_language fallback powered by NLLanguageRecognizer.

Availability

• The crate weak-links Translation.framework, so the typed Language, LanguagePair, TranslationConfiguration, TranslationResponse, and LanguageRecognition helpers work on macOS 14+.
• LanguageAvailability requires macOS 15+.
• Manual TranslationSession construction is currently available on macOS 26+ through TranslationSession(installedSource:target:); the crate surfaces those APIs and returns structured TranslationError values on older systems.

Async API

Enable the async feature to use executor-agnostic futures backed by Swift Task thunks and doom-fish-utils completion helpers:

translation-rs = { version = "0.3", features = ["async"] }

The async surface currently includes:

• AsyncTranslationSession::translate
• AsyncTranslationSession::translations
• AsyncTranslationSession::prepare_translation
• AsyncLanguageAvailability::status
• AsyncLanguageAvailability::supported_languages

See examples/10_async_translate.rs and examples/11_async_availability.rs for end-to-end usage with pollster::block_on.

Examples

The crate ships numbered examples for every logical area plus an end-to-end framework smoke test:

• 01_language_roundtrip
• 02_language_pair_roundtrip
• 03_translation_error_messages
• 04_language_availability_smoke
• 05_translation_configuration_lifecycle
• 06_translation_response_roundtrip
• 07_language_recognition_smoke
• 08_translation_session_smoke
• 09_framework_smoke
• 10_async_translate (requires --features async)
• 11_async_availability (requires --features async)

Run the sync examples with:

for ex in 01_language_roundtrip 02_language_pair_roundtrip 03_translation_error_messages 04_language_availability_smoke 05_translation_configuration_lifecycle 06_translation_response_roundtrip 07_language_recognition_smoke 08_translation_session_smoke 09_framework_smoke; do
  cargo run --example "$ex"
done

Run the async examples with:

cargo run --features async --example 10_async_translate
cargo run --features async --example 11_async_availability

Coverage

See COVERAGE.md for the API-by-API audit against the active macOS SDK.

License

Licensed under either Apache-2.0 or MIT at your option.

Re-exports

pub use language::Language;

pub use language_availability::LanguageAvailability;

pub use language_availability::LanguageAvailabilityStatus;

pub use language_pair::LanguagePair;

pub use language_recognition::detect_language;

pub use language_recognition::recognize_language;

pub use translation_attributes::SkipTranslationAttribute;

pub use translation_attributes::SkipTranslationAttributeValue;

pub use translation_attributes::TranslationAttributedRun;

pub use translation_attributes::TranslationAttributedString;

pub use translation_attributes::TranslationAttributes;

pub use translation_attributes::TranslationAttributesDecodingConfiguration;

pub use translation_attributes::TranslationAttributesEncodingConfiguration;

pub use translation_configuration::TranslationConfiguration;

pub use translation_error::TranslationError;

pub use translation_response::TranslationResponse;

pub use translation_session::TranslationBatchResponse;

pub use translation_session::TranslationRequest;

pub use translation_session::TranslationSession;

pub use translation_session::TranslationSessionConfiguration;

pub use translation_session::TranslationStrategy;

Modules

async_apiasync

Async wrappers for Translation.framework operations. Async API for Translation

availability

Availability APIs mirroring Translation.framework’s LanguageAvailability.

detection

Language recognition helpers used alongside Translation.framework.

error

Error re-exports for Translation.framework operations.

ffi

language

Language identifier types used by Translation.framework.

language_availability

LanguageAvailability bindings for Translation.framework.

language_pair

Source/target language pair types for Translation.framework.

language_recognition

NaturalLanguage-backed detection helpers for Translation workflows.

prelude

Common Translation.framework wrapper types for glob imports.

session

Session re-exports for Translation.framework workflows.

translation_attributes

Translation attribute helpers for attributed text workflows.

translation_configuration

Mutable configuration helpers for Translation.framework sessions.

translation_error

Error types for Translation.framework operations.

translation_response

Response types returned by Translation.framework translations.

translation_session

Core TranslationSession wrappers for Translation.framework.