Overview¶

This section shows a guided example using the CLI and the python API.

First of all, make sure that the spanglish service is up and running (take a look to the guide if you haven't done it yet). Using docker compose, un a separate window run docker compose up, or docker directly if prefered (just use the run.sh file).

CLI¶

For convenience, a command line app can be installed, with the functionality just to translate a markdown file for the moment (check the README file for the installation instructions):

$ translate-md tests/data/post-example.md

By default a new file will be created at tests/data/post-example.es.md, otherwise use --new-filename to give a different name.

Python API¶

Lets see a tour of the Python API.

Instantiate the client¶

Lets start by importing the code

from translate_md.client import SpanglishClient
client = SpanglishClient()
print(client)
SpanglishClient(http://localhost:8000/)

By default it assumes the server is running on http://localhost:8000/.

Translate a piece of text¶

michael_scott = """Sometimes I'll start a sentence and I don't even know where it's going. I just hope I find it along the way."""
print(client.translate(michael_scott))

which would yield:

A veces voy a empezar una frase y ni siquiera sé a dónde va.

Translate a batch of texts¶

dwitght_schrute = """Whenever I'm about to do something, I think, 'Would an idiot do that?' and if they would, I do not do that thing."""
michael_scott = """I knew exactly what to do, but in a much more real sense I had no idea what to do."""
andy_bernard = "Sorry I annoyed you with my friendship"
jim_halpert = "Bears, beets, Battlestar Galactica."
creed_bratton = """Oh, you’re paying way too much for worms. Who’s your worm guy?"""
oscar_martinez = """I consider myself a good person, but I'm gonna try to make him cry."""
prison_mike = "The worst thing about prison was the Dementors."
kelly_kapoor = """Who says exactly what they’re thinking? What kind of a game is that?"""
stanley_hudson = """Boy, have you done lost your mind? Cause I’ll help you find it!"""
print(client.translate_batch([
    dwitght_schrute, michael_scott, andy_bernard, jim_halpert,
    creed_bratton, oscar_martinez, prison_mike, kelly_kapoor,
    stanley_hudson
]))

Which would yield

[
    "Siempre que estoy a punto de hacer algo, pienso, '¿Haría eso un idiota?' y si lo hicieran, no lo hago.",
    'Yo sabía exactamente qué hacer, pero en un sentido mucho más real no tenía idea de qué hacer.',
    'Lo siento te molesté con mi amistad',
    'Osos, remolachas, Battlestar Galactica.',
    'Oh, tú’ estás pagando demasiado por gusanos. ¿Quién’ es tu gusano?',
    'Me considero una buena persona, pero voy a tratar de hacerlo llorar.',
    'Lo peor de la prisión fueron los Dementores.',
    '¿Quién dice exactamente lo que ellos’re pensando? ¿Qué tipo de juego es eso?',
    'Muchacho, ¿has perdido la cabeza? Porque yo’ te ayudaré a encontrarlo!'
]

Translate a markdown file¶

The following example uses a sample file placed in the tests folder of this repo. You can copy the content to a file and change the filename variable appropriately to run the example (If new_filename argument is not given if will be automatically generated, in this case changing the name to post-example.es.md on the same directory):

from pathlib import Path
filename = Path.cwd() / "tests/data/post-example.md"
new_filename = Path.home() / "Downloads" / "example_file.es.md"
client.translate_file(filename, new_filename=new_filename)

TODO: Write result before and after

Dealing with the markdown file¶

In case its needed, one can deal with the markdown file without a problem:

import translate_md.markdown as md

md_content = md.read_file(filename)
proc = md.MarkdownProcessor(md_content)

md.MarkdownProcessor is a wrapper of the wonderful markdown-it-py's MarkdownIt class to deal with the files tokens.

>>> print(proc)
MarkdownProcessor(54)

We can access to the text content which will be translated by calling the get_pieces method:

pieces = proc.get_pieces()

This will return the list of paragraphs to be sent to the API:

>>> print(pieces[:3])
[
    'This is a sample article to showcase the capabilities of the program. Its a moddification of a sample file from gohugo repo.',
    '## Title',
    "This paragraph contains the presentation of the blog post. It's usually written with some type of heading."
]

After getting these pieces translated we should update the content of the original file and we are ready to obtain the translated file

proc.update(pieces)
proc.write_to(new_filename)

Thats it!

A note on the expected behavior¶

For the moment, there is no cleaning of the markdown content before being sent to the translator, which can create some errors with the content obtained. The output file obtained should be treated as a draft.

The following table shows a comparison of the input file (left) and the output (right):

English version	Versión en castellano
post-example-screenshot	post-example-screenshot.es

The images may be small, in case you want to see them they are placed under under the tests/data folder.

We can see the text paragraphs translated (the front-matter, comments, code blocks and figures (only when written as a separate paragraph)), with the remaining content untouched. Some errors are yet to be treated, like keeping the lists with the appropriate format.