translator.library Reference

Function reference for translator.library, based on the interface files in the AmigaOS NDK 3.2 Release 4: SFD/translator_lib.sfd, FD/translator_lib.fd, Include_H/clib/translator_protos.h, Include_H/libraries/translator.h and Include_I/lvo/translator_lib.i.

This page documents 1 function of translator.library. The NDK carries no autodoc for it, so this page is built from the SFD/FD files, the prototypes and the include files only.

Editorial markers: V36 = OS 2.0, V37 = OS 2.04, V39 = OS 3.0, V40 = OS 3.1, V44 = OS 3.5, V45 = OS 3.9, V47 = OS 3.2.

Background

translator.library belongs with the speech system. Its headers carry the same "Joseph Katz/Mark Barton" copyright as <devices/narrator.h> (the V37 narrator.device include), and both share the error values -2 ("Can't allocate memory") and -4 ("Error in MakeLibrary call"). The only narrator.device file in NDK 3.2 is that include file. Its error list includes ND_PhonErr (-20, "Phoneme code spelling error"), which indicates that the device works on phoneme strings.

The NDK 3.2 R4 still ships every interface file for the library, all at version 47.1:

File $VER
SFD/translator_lib.sfd 47.1 (30.11.2021)
Include_H/libraries/translator.h 47.1 (29.7.2019)
Include_I/libraries/translator.i 47.1 (29.7.2019)
Include_H/clib/translator_protos.h 47.1 (30.11.2021)
Include_H/pragmas/translator_pragmas.h 47.1 (30.11.2021)
Include_H/proto/translator.h 47.4 (6.12.2021)

Library interface

Item Value
Library name translator.library
Base variable TranslatorBase (struct Library *)
Bias 30 (first and only public vector)
Include <libraries/translator.h>, <proto/translator.h>

Function index

Translate()

Since: 1.3+ Translate - convert an input string into an output buffer

Synopsis

result = Translate(inputString, inputLength, outputBuffer, bufferSize)
D0                 A0           D0           A1            D1

LONG Translate(CONST_STRPTR inputString, LONG inputLength, STRPTR outputBuffer, LONG bufferSize);

Vector
LVO _LVOTranslate equ -30 (Include_I/lvo/translator_lib.i)
SAS/C pragma #pragma libcall TranslatorBase Translate 1e 190804
Aztec/Maxon/StormC pragma #pragma amicall(TranslatorBase, 0x1e, Translate(a0,d0,a1,d1))
FD Translate(inputString,inputLength,outputBuffer,bufferSize)(a0,d0/a1,d1)

Inputs

Parameter Register Type Meaning (from the parameter names)
inputString A0 CONST_STRPTR Source text
inputLength D0 LONG Number of input characters
outputBuffer A1 STRPTR Destination buffer
bufferSize D1 LONG Size of the destination buffer

Results

LONG in D0. <libraries/translator.h> defines these as the "Translator error return codes":

Constant Value Comment from the header
TR_NotUsed -1 "This is an oft used system rc"
TR_NoMem -2 "Can't allocate memory"
TR_MakeBad -4 "Error in MakeLibrary call"

The assembler include <libraries/translator.i> defines the same three values as EQUs.

Example

#include <exec/types.h>
#include <libraries/translator.h>
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/translator.h>

struct Library *TranslatorBase;

int main(void)
{
    static const char text[] = "hello amiga";
    char out[256];
    LONG rc;

    if ((TranslatorBase = OpenLibrary("translator.library", 0)) != NULL)
    {
        rc = Translate(text, sizeof(text) - 1, out, sizeof(out));
        switch (rc)
        {
            case TR_NoMem:   PutStr("out of memory\n"); break;
            case TR_MakeBad: PutStr("MakeLibrary error\n"); break;
            default:         Printf("Translate() returned %ld\n", rc); break;
        }
        CloseLibrary(TranslatorBase);
    }
    else
        PutStr("cannot open translator.library\n");

    return 0;
}

Always check the result of OpenLibrary(). The library may not be installed on the target system. The NDK headers only name the negative TR_* codes. The meaning of other return values, and the format of the output buffer, are not described in the NDK files, so the example only reports the code it gets back.

Assembler call

        INCLUDE "libraries/translator.i"

        move.l  _TranslatorBase,a6
        lea     InText,a0
        moveq   #InTextLen,d0
        lea     OutBuf,a1
        move.l  #OutBufSize,d1
        jsr     -30(a6)              ; _LVOTranslate
        tst.l   d0
        bmi.s   .error               ; negative: TR_* code

See also

<devices/narrator.h>, exec.library Reference (OpenLibrary())

See Also

Sources: NDK 3.2 R4 SFD/translator_lib.sfd, FD/translator_lib.fd, Include_H/libraries/translator.h, Include_I/libraries/translator.i, Include_I/lvo/translator_lib.i, Include_H/clib/translator_protos.h, Include_H/pragmas/translator_pragmas.h, Include_H/pragma/translator_lib.h, Include_H/proto/translator.h, Include_H/devices/narrator.h Updated: 2026-11-13