AR282 EN user doc almsot done

doc/user/EN/analysis.md

@@ -1,84 +1,84 @@
 # Analysis documentation
 
-## Comparaison des données entre les bases
+## Comparing data bewteen databases
 
-Une fois toutes les informations récupérées, compare les données entre les deux bases :
+Once all data is retrieved, compares data between the two databases :
 
-* Pour le titre : génère un score de similarité, d'appartenance, d'inversion et d'inversion appartenance à l'aide de [la distance de Levenshtein](https://fr.wikipedia.org/wiki/Distance_de_Levenshtein)
-* Pour les dates de publication : vérifie si l'un des dates de la base de données d'origine est comprise dans l'une des dates de la base de données de destination (ne compare pas si les dates ne sont pas renseignées)
-* Pour les éditeurs : compare chaque éditeur de la base de données d'origine avec chaque éditeur de la base de donnée de destination en génèrant un score de similarité, puis renvoie la paire avec le score le plus élevé.
+* Title : generate a simple ratio, a partial ratio, a token sort ratio and a token set ratio using [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance)
+* Publication dates : checks if one of the origin database date is equal to one of the target databes date (does not check if no dates are found)
+* Publisher : compares every publisher from the origin database record to every publisher from the target database record using a simple ratio, then returns the couple with the highest ratio
 
-Ensuite, le script valide ou non chaque critère de comparaison de l'analyse choisie et indique un degré de validation pour cette comparaison.
+Then, the script validate or not every comparison criteria for the chosen analysis and outputs a validation grade for this comparison.
 
-## Analyse des résultats des correspondances
+## Matching results analysis
 
-L'analyse des résultats des correspondances se base sur 3 critères :
+The matching results analysis is based on 3 criterias :
 
-1. sur les 4 formes du titre étudiée, la correspondance des titres est supérieure à un seuil minimum pour au moins X d'entre eux
-1. la correspondance des éditeurs est supérieure à un seuil minimum
-1. la correspondance des dates de publication est prise en compte ou non
+1. Of the 4 title ratios used, at least X of them meet the required floor
+1. The publishers ratio meet the required floor
+1. The publication date is used
 
-## Résultats de l'analyse
+## Analysis results
 
-L'analyse renvoie 5 données :
+The analysis output 5 data :
 
-* _Validation globale_ : résultat final de l'analyse, prend la valeur :
-  * _Vérifications complètes_ : tous les critères sélectionnés sont validés
-  * _Vérifications partielles_ : une partie des critères sélectionnés sont validés
-  * _Vérifications KO_ : aucun des critères sélectionnés n'a été validé
-  * _Pas de vérification_ : l'analyse choisie n'effectue aucune vérification
-  * Si rien ne s'affiche, l'analyse n'a pas eu lieu
-* _Nombre de validations réussies_ : le nombre de critéères sélectionnés qui ont été validés
-* _Validation des titres_ :
-  * `True` si le nombre de formes du titre ayant un score supérieur ou égal au seuil minimum requis est supérieur ou égal au nombre minimum requis
-  * `False` si ce n'est pas le cas
-* _Validation des éditeurs_
-  * `True` si le score de correspondance de la pair d'éditeur choisie est supérieur ou égal au seuil minimum requis
-  * `False` si ce n'est pas le cas
-* _Validation des dates_
-  * `True` si l'une des dates de Koha correspond à l'une de celles du Sudoc
-  * `False` si ce n'est pas le cas
+* _Global validation result_ : analysis final result, can be :
+  * _All checks were successful_
+  * _Checks partially successful_ : only some checks were succesful
+  * _All checks failed_
+  * _No checks_ : chosen analysis does not check any criteria
+  * If nothing is displayed, the analysis did not happen
+* _Number of successful checks_ : the number of checks that were OK
+* _Title check_ :
+  * `True` if the number of title checks was superir or aquel to the minimum required
+  * `False` if it was nto the case
+* _Publishers check_
+  * `True` if the publishers ratio is superior or equal to the required floor
+  * `False` if it was nto the case
+* _Dates check_
+  * `True` if one of the origin database date matches one of the target database ones
+  * `False` if it was nto the case
 
-_Note : les détails (notamment les scores de similarités) sont disponibles à la fin des colonnes udu fichier de sortie_
+_Note : details (notably ratios) are available at the end of CSV export columns_
 
-## Configurations des analyses par défaut
+## Default analysis configuration
 
-_Si les seuils minimum sont configurés à 0, l'analyse ignorera le critère en question._
+_If the floor are configured to `0`, the critera will be ignored_
 
-### Analyse 0 : Aucune analyse
+### Analysis 0 : Aucune analyse
 
-* Seuil minimum pour la correspondance des titres : `0`
-* Nombre minimum de formes du titre devant être supérieur au seuil : `0`
-* Seuil minimum pour la correspondance des éditeurs : `0`
-* Utilisation de la date de publication : `NON`
+* Floor ratio for title match : `0`
+* Minimum ratio number matching : `0`
+* Floor ratiofor publisher match : `0`
+* Use publication date : `NON`
 
-### Analyse 1 : Titre 80 (3/4), Editeurs 80, Dates
+### Analysis 1 : Titre 80 (3/4), Editeurs 80, Dates
 
-* Seuil minimum pour la correspondance des titres : `80`
-* Nombre minimum de formes du titre devant être supérieur au seuil : `3`
-* Seuil minimum pour la correspondance des éditeurs : `80`
-* Utilisation de la date de publication : `OUI`
+* Floor ratio for title match : `80`
+* Minimum ratio number matching : `3`
+* Floor ratiofor publisher match : `80`
+* Use publication date : `OUI`
 
-### Analyse 2 : Titre 90
+### Analysis 2 : Titre 90
 
-* Seuil minimum pour la correspondance des titres : `90`
-* Nombre minimum de formes du titre devant être supérieur au seuil : `4`
-* Seuil minimum pour la correspondance des éditeurs : `0`
-* Utilisation de la date de publication : `NON`
+* Floor ratio for title match : `90`
+* Minimum ratio number matching : `4`
+* Floor ratiofor publisher match : `0`
+* Use publication date : `NON`
 
-### Analyse 3 : Titre 95, Editeurs 95
+### Analysis 3 : Titre 95, Editeurs 95
 
-* Seuil minimum pour la correspondance des titres : `95`
-* Nombre minimum de formes du titre devant être supérieur au seuil : `4`
-* Seuil minimum pour la correspondance des éditeurs : `95`
-* Utilisation de la date de publication : `NON`
+* Floor ratio for title match : `95`
+* Minimum ratio number matching : `4`
+* Floor ratiofor publisher match : `95`
+* Use publication date : `NON`
 
-## Configurer une analyse
+## Configure an analysis
 
-Pour ajouter une nouvelle analyse, il faut rajouter un nouvel objet dans `analysis.json` avec les clefs suivantes :
+To add a new analysis, add a new object in `analysis.json` with the following keys :
 
-* `name` `(str)`: nom de l'analyse qui s'affichera dans les interfaces
-* `TITLE_MIN_SCORE` (`int`) : seuil minimum requis pour que la correspondances des titres soit considérée comme OK
-* `NB_TITLE_OK` (`int`) : nombre minimum de correspondance de formes de titre requis pour que le critère de correspondance des titres soit considéré comme OK
-* `PUBLISHER_MIN_SCORE` (`int`) : seuil minimum requis pour que la correspondances des éditeurs soit considérée comme OK
-* `USE_DATE` (`bool`) : utilisation du critère correspondance des dates de publication
+* `name` `(str)`: interface displayed analysis name
+* `TITLE_MIN_SCORE` (`int`) : floor ratio for title matching to be OK
+* `NB_TITLE_OK` (`int`) : minimum number of title matches for considering the entire title criteria to be OK
+* `PUBLISHER_MIN_SCORE` (`int`) : floor ratio for publishers matching to be OK
+* `USE_DATE` (`bool`) : use publication date

doc/user/EN/how_to_use.md

@@ -1,71 +1,71 @@
 # How to use _Find and Compare Records_
 
-Une fois l'application téléchargée et le fichier `sample.env` renommé en `.env`, vous pouvez exécuter l'application.
+Once the application downloaded et the `sample.env` file renammed to `.env`, you can execute the application.
 
-Pour ce faire :
+To do it :
 
-* Exécuter le fichier `FCR.bat` situé à la racine de l'application
-* Ou, avec l'invite de commande, placez-vous dans le répertoire de l'application (avec `cd`) et exécuter avec Python le fichier `main_gui.py`
+* Execute the file `FCR.bat` found at the root of the application
+* Or, using the command terminal, go to the application folder (using `cd`) and execute with Python the file `main_gui.py`
 
-## Étape 1 : configuration principale
+## Step 1 : main configuration
 
-![Écran principal de _Find and Compare Records_](./img/UI_main_screen.png)
+![_Find and Compare Records_ main screen](./img/UI_main_screen.png)
 
-_Le bouton en haut à droite permet de changer la langue de l'interface du entre le français et l'anglais._
+_The top-right button allows to switch language between french and english._
 
-Cet écran permet de configurer les paramètres généraux de l'application à savoir :
+This screen is used to configure the main settings of the application :
 
-* Le traitement qui sera exécuté _([voir plus d'informations sur les traitements disponibles](./processings.md))_
-* Les chemins d'accès :
-  * Au fichier à analyser _([voir plus d'informations sur ce fichier](./input_file.md))_
-  * Au dossier qui contiendra les fichiers de résultats
-  * Au dossier qui contiendra le fichier des journaux
-* Le nom du service (qui sert uniquement pour les journaux, notamment pour nommer le fichier)
-* Le niveau de journalisation
+* The processing to use _([see more about available processings](./processings.md))_
+* Files path :
+  * To the input file _([see more about the input file](./input_file.md))_
+  * To the output folder
+  * To the folder containing the log file
+* The service name (only used for logs, notable namming the file)
+* The log level
 
-Le bouton _Sauvegarder ces paramètres d'exécution_ permet de sauvegarder les paramètres actuellement définis sur l'interface pour une prochaine exécution (langue comprise).
+The _Save these executon settigs_ button can be used to save the settings currently displayed for a future execution (including language).
 
-Une fois cet écran correctement paramétré (voire sauvegardé), le bouton _Suivant (configuration du traitement)_ permet de passer à la seconde étape.
+Once this screen correctly configured (and possibly saved), the _Next (processing configuration)_ button is used to go to nest step.
 
-## Étape 2 : configuration du traitement
+## Step 2 : processing configuration
 
-Ce nouvel écran contient 3 onglets :
+This new screen has 3 tabs :
 
-* _Configuration principale du traitement_
-* _Configuration des mappings_
-* _Choix des mappings de BDD_
+* _Processing main configuration_
+* _Mapping configuration_
+* _Chose database mappings_
 
-Par ailleurs, sous le titre de l'écran, le traitement choisi est rappelé.
+A text under the screen title reminds which processing will be used.
 
-Une fois la configuration de tous les onglets terminée, le bouton _Lancer l'analyse_ permet de passer à la troisième et dernière étape.
+Once every tab is correctly configured, the _Start analysis_ button is used to go to the third and last step.
 
-### Onglet _Configuration principale du traitement_
+### _Processing main configuration_ tab
 
-Cet onglet n'affiche pas les mêmes options selon le traitement choisi.
+This tab displayes settings is based on the chosen processing.
 
-Le bouton _Sauvegarder les paramètres principaux de ce traitement_ permet de sauvegarder les paramètres actuellement définis sur l'interface pour une prochaine exécution.
+The _Save main processing configuration settings_ button is used to saved currently displayed settings for a fututre execution.
 
 
-#### Suite `BETTER_ITEM`
+#### `BETTER_ITEM` suite
 
-![Écran de configuration du traitement, onglet de configuration principale pour `BETTER_ITEM`](./img/UI_processing_conf_main_tab_better_item.png)
+![Processing configuration screen, main configuration tab for `BETTER_ITEM`](./img/UI_processing_conf_main_tab_better_item.png)
 
-* URL de la base de données d'origine : ce traitement récupère les données de la base de données d'origine via les APIs de celle-ci, il faut donc indiquer __le nom de domaine qui permet d'exécuter les APIs__
-* ILN : l'ILN de l'établissement concerné _(utilisé pour filtrer les identifiants dans les autres bases de données)_
-* RCR : le RCR de la bibliothèque concernée _(utilisé pour filtrer les exempalires et code-barres d'exemplaires)_
+* Origin database URL : this processing retrieve data from the origin database through its APIs, the URL should be the __domain name for API exution__
+* ILN : library ILN _(used to filter identifiers in other databases)_
+* RCR : library RCR _(used to filter items & items barcodes)_
 
 #### `MARC_FILE_IN_KOHA_SRU`
 
-![Écran de configuration du traitement, onglet de configuration principale pour `MARC_FILE_IN_KOHA_SRU`](./img/UI_processing_conf_main_tab_marc_file_in_koha_sru.png)
+![Processing configuration screen, main configuration tab for `MARC_FILE_IN_KOHA_SRU`](./img/UI_processing_conf_main_tab_marc_file_in_koha_sru.png)
 
-* URL de la base de données de destination : ce traitement récupère les données de la base de données de destination via les APIs de celle-ci, il faut donc indiquer __le nom de domaine qui permet d'exécuter les APIs__ (ou se connecter au SRU si c'est via le SRU)
-* Filtre 1, 2 & 3 : filtre libres, configurables en fonction de la base de données de destination (ou d'origine)
-  * Le filtre 1 est utilisé pour filtrer les exempalires et code-barres d'exemplaires
-  * Pour lier des filtres à des données, il est nécessaire de modifier le code dans `cl_PODA.py` ([voir la documentation développeur sur les PODAs à ce sujet](../../PODAs.md#database))
+* Target database URL : this processing retrieve data from the origin database through its APIs, the URL should be the __domain name for API exution__ (or the SRU if it is used)
+* Filter 1, 2 & 3 : free filters, configurable based on target database (or origin)
+  * Filter 1 is used to filter items & items barcodes
+  * To link filters to data, the code in `cl_PODA.py` needs to be edited ([see developper documentation about PODAs on that subject](../../PODAs.md#database))
 
-### Onglet _Configuration des mappings_
+### _Mapping configuration_ tab
 
-![Écran de configuration du traitement, onglet de configuration des mappings](./img/UI_processing_conf_db_conf_tab.png)
+![Processing configuration screen, mapping configuration tab](./img/UI_processing_conf_db_conf_tab.png)
 
 Cet onglet est le plus complexe mais également celui qui, une fois sauvegardée, n'a plus besoin d'être reconfiguré.
 
@@ -105,18 +105,18 @@ Renseignez dedans le numéro du champ voulu.
 Pour sauvegarder la modification effectuée sur le champ, cliquez sur le bouton _Sauvegarder ce champ MARC_.
 Cette opération est nécessaire __pour chaque champ__, sinon les données ne seront pas sauvegardées.
 
-### Onglet _Choix des mappings de BDD_
+### _Chose database mappings_ tab
 
-![Écran de configuration du traitement, onglet de choix des mappings de base de données](./img/UI_processing_conf_chose_mapping_tab.png)
+![Processing configuration screen, chosing database mappings tab](./img/UI_processing_conf_chose_mapping_tab.png)
 
-Cet onglet est le plus simple puisqu'il suffit de choisir le mapping que l'on souhaite attribuer à la base de donnée d'origine et à la base de donnée de destination.
+This tab is the easiest as it only requires to chose the mapping we want to use for the origin database & for the target database.
 
-Le bouton _Sauvegarder les mappings de BDD choisis_ permet de sauvegarder les paramètres actuellement définis sur l'interface pour une prochaine exécution.
+The _Save chosen database mappings_ button is used to save currently displayed settings for future execution.
 
-## Étape 3 : choisir l'analyse
+## Step 3 : chosing the analysis
 
-![Fenêtre de choix de l'analyse](./img/UI_chose_analysis.png)
+![Chosing the analysis screen](./img/UI_chose_analysis.png)
 
-Cette dernière fenêtre permet de choisir l'analyse voulue parmis celles définies dans le fichier `json_configs/analysis.json`.
+This last screen is used to chose the analysis we want to execute, from the ones defined in the `json_configs/analysis.json` file.
 
-Le bouton _Lancer le script principal_ permet (enfin) de lancer le script.
+The _Start main script_ button is used to start the script.