Synopsis

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

Function

Convert a bounded byte string to phoneme text using the translator's
letter-to-sound rules. This call produces text, not audio. The default
tables implement English letter-to-sound conversion; a loaded speech
resource may supply different translation tables.

Inputs

inputString - Readable input bytes. May be NULL only when inputLength
    is zero. Input and output storage must not overlap.
inputLength - Nonnegative maximum number of input bytes to examine.
    A NUL byte ends translation early; no terminator is required when
    the supplied length bounds the input. This is a byte count, not a
    Unicode character count.
outputBuffer - Non-NULL writable output storage owned by the caller.
outputLength - Positive capacity in bytes, including the terminating
    NUL. Supply the actual accessible capacity.

Result

Zero on reported completion. A negative value reports rejected
arguments, an overlong internal word or detected output exhaustion.
Invalid arguments return -1 without modifying the output buffer.

After valid arguments reach the translation core, the output is NUL-
terminated, including on a reported translation failure. Failure may
leave partial phoneme text. A core failure returns the negative count
of input bytes not yet read, or -1 if none remain. This is not a count
of untranslated characters or a reliable offset for resuming input.

No required output size, bytes-written count or distinct error code
for each failure class is returned. errno and IoErr() are not set by
this call. See BUGS: zero does not guarantee complete stress marking.

Notes

Include <proto/translator.h> and keep translator.library open while
calling. The library attempts to load DEVS:Speech/speech.iff during
initialization. If no translator table is available, it uses compiled
defaults. Translate() performs no resource reload or file I/O itself.

ASCII lowercase is converted to uppercase before rule matching.
Bytes below 0x20, bytes at or above 0x80, DEL and ']' become spaces;
NUL additionally ends input. This is not UTF-8 decoding or a locale-
dependent text conversion. Two consecutive '#' bytes participate in
the core's end-marker handling and can stop translation before the
end of the supplied input. Do not use this interface to preserve
arbitrary binary data or non-ASCII spelling.

Rule output can include punctuation, spaces and stress digits. The
default conversion of "hello world" with ample output capacity is
"/HEH4LOW WER4LD ", including its trailing space. Output length need
not match input length. An empty input produces an empty string.

The internal word-fill limit is 100 bytes, including the scanner's
boundary/look-ahead behavior. Long unbroken input can fail even with
ample output capacity. Increasing outputLength cannot repair that
condition. Split long text at suitable text boundaries, not at an
assumed position derived from a negative return value.

The call uses per-call state and caller-owned output; it retains
neither input nor output. Do not modify either buffer during the
call. The translation core performs no dynamic allocation, exposes
no cancellation callback and supplies no timeout. Resource loading
during OpenLibrary() has a separate allocation and I/O lifetime.

Bugs

Output exhaustion during final stress insertion is not always
propagated to the result. With the compiled default tables, "hello"
and an outputLength of 9 or 10 can return zero with "/HEHLOW "; an
outputLength of 11 produces "/HEH4LOW ". Merely fitting the final
visible text plus NUL is not a reliable completeness test. The core
must check the final overflow state before promising complete output.

Read-ahead means a negative result cannot safely identify a source
suffix whose translation can be appended to the partial output.
Retry from the original input with adequate capacity after a capacity
failure; distinguish long-word failures separately in the caller.

See also

`OpenLibrary()`_ `CloseLibrary()`_