Skip to content

UC3: Vertalen woorden/teksten

Functioneel ontwerp use case: UC3: Vertalen woorden/teksten

1. Front-end componenten

Voor deze use case is één nieuwe pagina gemaakt, namelijk:

  • Vertalingen statistieken pagina: Hier kan de gebruiker de statistieken van de vertalingen zien, zoals hoeveel vertalingen nog leeg zijn, hoeveel kosten hij heeft opgebouwd en wie er verantwoordelijk is voor de aanpassingen van de vertalingen.

Sommige componenten die in UC2 geïmplementeerd zijn, zijn ook in deze use case gebruikt. Voor overige verantwoordingen of overige onderdelen, zie UC2. De onderdelen van UC2 die niet aangepast zijn in deze use case zijn niet meegenomen in het diagram, deze zijn terug te vinden in UC2.

De volgende componenten zijn niet terug te vinden in het diagram, omdat deze alleen voor een mooie weergave van de namespaces dropdown zorgen.

NamespaceControl, NamespaceOption en NamespaceValueContainer: Dit component wordt gebruikt om een namespace te selecteren uit de namespaces die in het versiebeheer systeem project staan. Dit component gebruikt als basis nog steeds het template FormSelect component, maar de Option, Control en ValueContainer componenten daarbinnen zijn vervangen om de namespaces mooi weer te kunnen geven, om om aam te kunnen geven welk bestandstype de namespace heeft.

UC3 front-end componenten
Afbeelding: Front-end componenten

2. Back-end componenten

In het volgende diagram zijn de verschillende onderdelen van de back-end van UC3 weergegeven. Sommige onderdelen zijn weggelaten, omdat deze in UC2 al toegelicht zijn. Voor overige verantwoordingen of overige onderdelen, zie bovenstaande link.

In deze use case zijn een aantal nieuwe functionaliteiten toegevoegd in de ProjectTranslationsService, ook zijn er nieuwe componenten voor de stats toegevoegd via de ProjectTranslationStatisticsController en ProjectTranslationStatisticsService.

De nieuwe functionaliteiten gaan over het vervangen van de vertalingen in de juiste bestanden, ook zijn een aantal modellen aangepast zodat de juiste namespace van de vertaling wordt opgeslagen. De nieuwe functionaliteiten zijn toegevoegd in de ProjectTranslationsService.

Modellen, interfaces en enums worden niet weergegeven in het diagram. Voor de verschillende versiebeheersystemen is een enum aanwezig, deze wordt gebruikt in de IVersionControlService interface. Voor de vertalingsbestanden is ook een enum aanwezig, deze wordt gebruikt in de ITranslationFileService interface. Dit zorgt ervoor dat er niet zomaar een string teruggegeven kan worden, maar dat er een van de waardes uit de enum teruggegeven moet worden. Bij doorontwikkeling van de applicatie kan er gemakkelijk een nieuwe waarde toegevoegd worden aan de enum, zonder dat er op meerdere plekken in de code aangepast moet worden.

UC3 back-end componenten
Afbeelding: Back-end componenten

3. Api endpoints

3.1 ProjectTranslationsController

Selectie vertalen

Endpoint: /api/ProjectTranslations/{projectId:guid}/translations
Method: POST
Rechten:: Ingelogd
Beschrijving: Een lijst van geselecteerde vertalingen vertalen naar een lijst van geselecteerde talen

Request 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "namespace": "string",
    "basePath": "string",
    "useAiTranslator": true,
    "translationsInLanguage":
    [
        {
            "namespace": {
                "fileType": "TranslationFileType",
                "fileName": "string",
                "fileNameWithoutExtension": "string",
                "filePath": "string",
                "languageCode": "string"
            },
            "translations": [
                {
                    "key": "string",
                    "value": "string"
                }
                ...
            ]
        }
        ...
    ]
}
Responses

Status code: 200 (OK), vertalingen zijn vertaald.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
  • geen vertalingsbestanden gevonden
  • vertalingen in de opgegeven targetLanguageCode bestaan al in het project
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Aangepaste vertalingen opslaan

Endpoint: /api/ProjectTranslations/{projectId:guid}/translations
Method: PUT
Rechten:: Ingelogd
Beschrijving: Nieuwe aangepaste vertalingen in een project opslaan

Request 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "namespace": "string",
    "basePath": "string",
    "useAiTranslator": false,
    "translationsInLanguage":
    [
        {
            "namespace": {
                "fileType": "TranslationFileType",
                "fileName": "string",
                "fileNameWithoutExtension": "string",
                "filePath": "string",
                "languageCode": "string"
            },
            "translations": [
                {
                    "key": "string",
                    "value": "string"
                }
                ...
            ]
        }
        ...
    ]
}
Responses

Status code: 200 (OK), vertalingen zijn opgeslagen.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
  • geen vertalingsbestanden gevonden
  • vertalingen in de opgegeven targetLanguageCode bestaan al in het project
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Ophalen prijs per karakter

Endpoint: /api/ProjectTranslations/price-per-character
Method: GET
Rechten:: Ingelogd
Beschrijving: Haalt de prijs per karakter

Responses

Status code: 200 (OK), prijs per karakter is opgehaald.

1
0.50000 (decimal)

Aanmaken nieuwe lege taal

Endpoint: /api/ProjectTranslations/{projectId:guid}/languages
Method: POST
Rechten:: Ingelogd
Beschrijving: Maakt een nieuwe taal in het project aan

Request 
1
2
3
4
{
    "targetLanguageCode": "string",
    "useAITranslator": false
}
Responses

Status code: 200 (OK), nieuwe taal is aangemaakt.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
  • geen vertalingsbestanden gevonden
  • vertalingen in de opgegeven targetLanguageCode bestaan al in het project
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 422 (Unprocessable Entity), mogelijke oorzaken:

  • targetLanguageCode is niet opgegeven
  • targetLanguageCode is te lang (max 10 characters)
  • useAITranslator is niet opgegeven
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

3.2 ProjectTranslationStatisticsController

Ophalen progressie ingevulde vertalingen project

Endpoint: /api/ProjectTranslationStatistics/{projectId:guid}/completion
Method: GET
Rechten:: Ingelogd
Beschrijving: Haalt het aantal ingevulde en totaal aantal vertalingen op

Responses

Status code: 200 (OK), progressie is opgehaald.

1
2
3
4
{
    "totalTranslations": 0,
    "translationsCompleted": 0
}

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
  • geen vertalingsbestanden gevonden
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Ophalen gemaakt kosten in periode

Endpoint: /api/ProjectTranslationStatistics/{projectId:guid}/costs
Method: GET
Rechten:: Ingelogd
Beschrijving: Haalt de gemaakte kosten voor project in opgegeven periode op
Query parameters:
- startDate (DateTime): De startDatum, vanaf wanneer er data opgehaald moet worden
- endDate (DateTime): De eindDatum, tot wanneer er data opgehaald moet worden

Responses

Status code: 200 (OK), kosten opgehaald.

1
0.50000 (decimal)

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Ophalen progressie ingevuld vertalingen per namespace

Endpoint: /api/ProjectTranslationStatistics/{projectId:guid}/namespaces
Method: GET
Rechten:: Ingelogd
Beschrijving: Haalt de progressie van vertaling op per namespace
Query parameters:
- selectedLanguageCode (string): De geselecteerde taal, optioneel

Responses

Status code: 200 (OK), namespaces opgehaald.

1
2
3
4
5
6
7
8
9
[
    {
        "namespaceName": "string",
        "basePath": "string",
        "totalTranslations": 0,
        "translationsCompleted": 0
    }
    ...
]

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
  • geen vertalingsbestanden gevonden
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Ophalen progressie ingevuld vertalingen per taal

Endpoint: /api/ProjectTranslationStatistics/{projectId:guid}/languages
Method: GET
Rechten:: Ingelogd
Beschrijving: Haalt de progressie van vertaling op per taal
Query parameters:
- selectedLanguageCode (string): De geselecteerde taal, optioneel

Responses

Status code: 200 (OK), talen opgehaald.

1
2
3
4
5
6
7
8
[
    {
        "languageCode": "string",
        "totalTranslations": 0,
        "translationsCompleted": 0
    }
    ...
]

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
  • geen vertalingsbestanden gevonden
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Ophalen vertaling audits in periode

Endpoint: /api/ProjectTranslationStatistics/{projectId:guid}/costs
Method: GET
Rechten:: Ingelogd
Beschrijving: Haalt aanpassingen van de vertalingen in het project in de opgegeven periode op
Query parameters:
- startDate (DateTime): De startDatum, vanaf wanneer er data opgehaald moet worden
- endDate (DateTime): De eindDatum, tot wanneer er data opgehaald moet worden

Responses

Status code: 200 (OK), audits opgehaald.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "characterCount": 0,
    "costPerCharacter": 0.0,
    "cost": 0.0,
    "type": "string",
    "languageCodes": [
        "string"
    ],
    "firstName": "string",
    "lastName": "string",
    "createdAt": "2021-06-01T12:00:00Z"
}

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • project is niet verbonden met versiebeheersysteem repository
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

4. Technisch keuzes

4.1. Aanmaken lege vertalingsbestanden voor (niet) ondersteunde talen

De applicatie maakt gebruik van een AI tool om vertalingen uit vertalingsbestanden in een project automatisch te vertalen. De AI tool ondersteund echter niet alle talen. Om er zeker van te zijn dat gebruikers altijd vertalingen kunnen toevoegen voor een taal naar keuze, ongeacht of deze taal ondersteund wordt door de AI tool, kan een gebruiker een lege lijst van vertalingsbestanden voor de gekozen taal aanmaken. De gebruiker zal alle vertalingen dan zelf in moeten vullen. Dit is mogelijk voor beide ondersteunde en niet ondersteunde talen van de AI Tool.

Bekijk de algemene technisch keuzes

5. Test cases

Er is gekozen om end to end tests te schrijven voor deze use case, omdat het bewerken van vertalingen een van de belangrijkste stappen in het vertalingsproces is. De meest gemakkelijke manier om alle scenario's te testen is door de flow van de use case te testen. Omdat de back-end en front-end in verbinding met elkaar staan aan de hand van de API endpoints, is het belangrijk dat deze verbinding goed werkt. De end to end tests valideren of de flow van de use case werkt, en of de back-end en front-end goed met elkaar communiceren.

Test cases
Afbeelding: Testcases van UC3

5.1 end-to-end tests

  • Test 1: Lege niet bestaande taal aanmaken
  • Test 2: Lege bestaande taal aanmaken

Json

  • Test 3: Filteren lege vertalingen JSON tabel
  • Test 4: Selectie van JSON tabel vertalen met AI, met lege vertalingen
  • Test 5: Selectie van JSON tabel vertalen met AI, zonder lege vertalingen
  • Test 6: Vertalingen in JSON tabel aanpassen en opslaan
  • Test 7: Vertalingen in JSON tabel aanpassen en verversen (niet opslaan)

ResX

  • Test 8: Filteren lege vertalingen ResX tabel
  • Test 9: Selectie van ResX tabel vertalen met AI, met lege vertalingen
  • Test 10: Selectie van ResX tabel vertalen met AI, zonder lege vertalingen
  • Test 11: Selectie van ResX tabel vertalen met AI, met alleen een standaard/terugval vertaling
  • Test 12: Selectie van ResX tabel vertalen met AI, zonder vertalingen in een rij
  • Test 13: Vertalingen in ResX tabel aanpassen en opslaan
  • Test 14: Vertalingen in ResX tabel aanpassen en verversen (niet opslaan)

Mail Template Editor

  • Test 15: Inhoud van mail template editors vertalen met AI, met lege vertalingen
  • Test 16: Inhoud van mail template editors van tabel vertalen met AI, zonder lege vertalingen
  • Test 17: Vertalingen in mail template editors aanpassen en opslaan
  • Test 18: Vertalingen in mail template editors aanpassen en verversen (niet opslaan)

Statistieken

  • Test 19: Gebruiker kan niet bij de statistieken pagina als het project niet gekoppeld is met een versiebeheersysteem
  • Test 20: Admin kan niet bij de statistieken pagina als het project niet gekoppeld is met een versiebeheersysteem, wordt naar de instellingen pagina gestuurd
  • Test 21: De berekening voor het aantal vertaalde vertalingen klopt
  • Test 22: De berekening voor de geselecteerde taal en bijbehorende namespaces klopt
  • Test 23: De audits in de geselecteerde periode kloppen