This tutorial is a quick and easy introduction to using the Fairslator API’s gender rewriting abilities. If you have a sentence which you want to rewrite into a different gender, the API endpoint /rewrite is the place to do it.

Rewriting the first person

You can, for example, send a JSON object like this to the /rewrite endpoint:

{
  "text": "Ich bin ein guter Student.",
  "lang": "de",
  "firstPerson": "f"
}

It says: please take this text (which means I am a good student.), it is in German (de), and change the first person to female (that’s what the f means). The “first person” is whoever is saying the text, the person who refers to themselves with pronouns such as I and me (or ich in German). After a few milliseconds the API will return this:

"Ich bin eine gute Studentin."

Notice how the male word Student has been changed to the female Studentin, and the two words before it have been changed too in order to keep them in grammatical agreement with the new word.

The values you can put in under firstPerson are either f (meaning: rewrite into female) or m (meaning: rewrite into male).

All of this works even if the first person is plural (German: We are the new doctors.):

{
  "text": "Wir sind die neuen Ärzte.",
  "lang": "de",
  "firstPerson": "f"
}

Output:

"Wir sind die neuen Ärztinnen."

Rewriting the second person

Everything you can do to the first person, you can do it to the second person too. The second person is whoever the text is addressing, typically through pronouns such as you. In this example we have a sentence meaning Are you my lawyer?

{
  "text": "Sind Sie mein Anwalt?",
  "lang": "de",
  "secondPerson": "f"
}

Output:

"Sind Sie meine Anwältin?"

Intermezzo: monolingual versus bilingual rewriting

Before we go any further let’s step aside and mention one important thing. If the text you are sending in to the API is a translation from a source test in another language, and if you have the source text, then it’s always a good idea to include the source text in the request, like this:

{
  "sourceText": "Are you my lawyer?",
  "sourceLang": "en",
  "text": "Sind Sie mein Anwalt?",
  "lang": "de",
  "secondPerson": "f"
}

The reason why it’s a good idea is that Fairslator sometimes uses the source text for disambiguation. For example, take the German sentence Sie sind hier. This sentence is ambiguous: it can mean either You are here or They are here. But if you include the English equivalent in the API request as sourceText, Fairslator will be able to use it as a clue for how it should understand the German sentence.

Rewriting third persons

Finally we get to the third person. A third person is somebody who is mentioned in the text using third-person pronouns such as he, she and they, or using nouns that don’t co-refer to any first- and second-person pronouns. Here it gets a little complicated: the thing with third persons is that there can be more than one of them in a single text. For example in this German sentence, which means the nurse saved the patient’s life, we have two third persons, the nurse and the patient. Each has its own gender and each can be rewritten independently.

In the Fairslator API, you identify each third person using a keyword taken from the text. You say, for each keyword, how you want to rewrite its gender:

{
  "sourceText": "The nurse saved the patient's life",
  "sourceLang": "en",
  "text": "Die Krankenschwester rettete dem Patienten das Leben.",
  "lang": "de",
  "thirdPersons": {
    "nurse": "m",
    "patient": "f"
  }
}

Output:

"Der Krankenpfleger rettete der Patientin das Leben."

If sourceText is present in your API request, you should take the keywords from the sourceText . If not, then take them from text. So, if sourceText were not included in this API request, the keywords would be in German: "Krankenschwester" and "Patient". If you’re not sure which keywords to pick, you should use the API’s /analyze endpoint first to analyze the text: one of the things it will tell you is what the third-person keywords are.

If this whole keywords thing is too complicated, then there is a shortcut available. You can use "*" (an asterisk) as a keyword, and it’ll mean “all third persons not captured by any other keywords”. So, if you simply want to rewrite all third persons into one gender, you can do it like this:

{
  "text": "Die Krankenschwester rettete dem Patienten das Leben.",
  "lang": "de",
  "thirdPersons": {
    "*": "m"
  }
}

Output (both nurse and patient are male now):

"Der Krankenpfleger rettete dem Patienten das Leben."

Generating gender-neutral neforms

Let’s look at one more detail before we finish this tutorial. Everywhere you can put m or f as the value of the desired target gender, you can also put b, which means “please generate gender-neutral neoforms”:

{
  "sourceText": "All students must register.",
  "sourceLang": "en",
  "text": "Alle Studenten müssen sich registrieren.",
  "lang": "de",
  "thirdPersons": {
    "*": "b"
  }
}

The output will be like this:

"Alle Student:innen müssen sich registrieren."

In German, Fairslator uses the Doppelpunkt to merge the male and female words into one. In some cases this is a good strategy, especially if it only affects a single word in the entire sentence. In other cases, when several words in a row contain the Doppelpunkt, the text can become difficult to read, so this strategy should be used sparingly.

In conclusion…

Congratulations, you now know pretty much everything you need about gender rewriting with the Fairslator API. Now’s a good time to look at other tutorials or to start using the API.