Bliss translator

Translate

GET /api/translate?q=Did+you+eat%3F or POST /api/translate with JSON:

{
  "text": "Did you eat?",
  "options": {
    "grammar": true,                // tense, plural and description indicators
    "punctuation": true,            // full stop, question mark or exclamation mark at the end
    "articles": false,              // include a/an/the (BCI's examples leave them out)
    "question_style": "opener",     // "opener": question first, full stop last (BCI rules)
                                    // "mark": question mark last; "both"
    "progressive": "action",        // "is eating": "action" (BCI) or "present_action"
    "names": "text",                // "text": English letters; "letters": Bliss letter characters
    "plural_after_number": true,    // false leaves the plural indicator off after a number
    "command_with_please": false,   // true adds the command "!" even when "please" is there
    "alternatives": 6,              // other senses to list per word (0-12)
    "use_model": false              // ask a local model about words with no symbol, if configured
  }
}

With GET, pass the same options as query parameters (model for use_model). An unknown value for question_style, progressive or names returns 400.

The response lists sentences, and each sentence lists units in Bliss order:

{
  "sentences": [{
    "text": "Did you eat?",
    "type": "question",               // statement, question, wh-question, command, exclamation, word
    "units": [
      {"text": "", "kind": "marker", "provenance": "grammar",
       "symbols": [{"key": "question", "id": 16445, "label": "question", ...}],
       "notes": ["'question' introduces a yes/no question"]},
      {"text": "eat", "kind": "word", "lemma": "eat", "provenance": "exact", "confidence": 0.9,
       "symbols": [{"key": "eat-(to)", "id": 13906, "label": "eat",
                    "drawn_indicator": "action", "indicator": "past_action",
                    "svg": "/api/bliss/render?id=13906&indicator=past_action",
                    "explanation": "food + action indicator"}],
       "notes": ["past action indicator replaces the action indicator"],
       "alternatives": [ ... ]}
    ],
    "skipped": [{"text": "Did", "reason": "do-support: tense goes on 'eat'"}]
  }],
  "summary": {"units": 3, "matched": 3, "approximate": 0, "unmatched": 0}
}

Limits: 1,000 characters per request; 60 requests per minute per client.

Draw a symbol

GET /api/bliss/render?id=13906&indicator=past_action returns SVG.

• id: BCI-AV number, or key: the drawing name (for example eat-(to)).
• indicator: an indicator kind replaces the one the drawing carries, or is added over the first character; none removes it; leave it out to draw the symbol as published.

Indicator kinds: action, past_action, future_action, conditional, past_conditional, future_conditional, passive, past_passive, future_passive, description, thing, plural, thing_plural, and the rest of the BCI-AV set.

Draw a sentence strip

POST /api/bliss/strip returns one SVG with the symbols side by side and English labels underneath.

{"items": [{"id": 14916, "label": "I"},
           {"id": 13906, "indicator": "past_action", "label": "ate"},
           {"label": "Sam"}],
 "labels": true}

Items without id or key are drawn as text, which is how names appear. "join": true continues the previous item's Bliss-word, so taller is sent as comparative more followed by tall with join: the characters sit at in-word spacing and the word's label is centered under both. A missing label uses the drawing's name; an empty one draws none. Each word is given at least the width of its label.

Look up a word

GET /api/bliss/lookup?q=walk&pos=VERB lists Bliss entries for an English word, best first, then entries whose gloss contains it. pos is optional (NOUN, VERB, ADJ, ADV, PRON...).

Search symbol libraries

GET /api/search?q=dog&sources=bliss,mulberry,arasaac&limit=5 searches Blissymbolics, Mulberry and ARASAAC. An API key (Authorization: Bearer ...) raises the rate limit but is not required. POST /api/search/batch takes {"queries": [...]}.

Communication boards

• POST /api/boards with {"title", "rows", "cols"} creates a board. The response includes edit_token once; keep it.
• GET /api/boards/<id> reads a board. Anyone with the ID can view it.
• PUT /api/boards/<id>, PUT /api/boards/<id>/cells and DELETE /api/boards/<id> need the header X-Board-Token: <edit_token>.
• GET /api/boards?ids=a,b summarizes boards you already know. There is no list of everyone's boards.
• Cells take a symbol_url that is an https:// address or a path on this server, a label of up to 120 characters, and hex colors such as #FFFFFF. Cells outside the grid are dropped.

Limits and access

• No key is needed. Requests are limited per IP address: translate and strip 30 a minute, lookup 60, render 300, search 30, board edits 30, new boards 10 an hour, anything else under /api/ 120 a minute. Over the limit returns 429.
• An API key (Authorization: Bearer ...) raises the search limit. A key that is not valid returns 401.
• Request bodies are limited to 256 KB (413), English text to 1,000 characters, search terms to 100, batch search to 10 terms, strips to 80 items.
• Browsers can call the API from this site only. Scripts and servers can call it from anywhere.

How translation works

1. spaCy tags and parses the English.
2. Grammar Bliss carries in indicators is moved onto the verb: did, will, would, have + participle and progressive be are dropped and become past, future, conditional or passive indicators. Infinitive to is dropped; articles are dropped unless requested.
3. Multiword glosses are matched first (thank you, turn off), then single words through their dictionary forms. Senses are ranked by part of speech, headword order and sense qualifiers that fit the sentence.
4. Words without a symbol fall back, in order, to a compound of two Bliss words, a WordNet synonym, a composition (opposite meaning + adjective, without + noun, person + verb), for adjectives the noun they relate to plus the description indicator (economic → economy) or a similar adjective (various → different), a broader WordNet term, a local model when configured, and finally the English word as text. Each BCI entry is matched to its WordNet meanings, and a fallback is used only when the meanings agree, so guy does not become the animal cat. Rejected candidates are listed under Change with "via": "unconfirmed".
5. Indicators follow BCI's fundamental rules: the action indicator marks every present form and the infinitive; past, future, conditional and passive replace it. Plural nouns take the plural indicator (thing-plural when the word carries a thing indicator). An added indicator goes over the word's classifier, skipping leading modifiers such as without or opposite meaning.
6. One word typed without punctuation is treated as a word, not a sentence: no markers are added, and it takes its most common reading (like is the verb).
7. Sentences follow BCI's examples: a yes/no question opens with question and a command with an exclamation mark, and both end with a full stop. Not goes before its verb. Bigger is one Bliss-word, comparative more + big. Each of these choices can be changed with the options above.

Licenses and credit

Parts herein © Blissymbolics Communication International (BCI), distributed under the Creative Commons BY-SA 4.0 licence (BCI-AV drawings and glosses). Word classes and derivation notes: the Blissary dictionary by Hannes Ljusås, CC BY-SA 4.0. Mulberry symbols: CC BY-SA. ARASAAC pictograms: Sergio Palao, Government of Aragon, CC BY-NC-SA. Service code: MIT, by Luke Steuber.