ComposantsComponents

ComposantsComponents › Fichier › GestionFile › Management

tChangeFileEncoding

tChangeFileEncoding

Fichier › GestionFile › Management Qualité de donnéesData Quality

Réécrit un fichier texte dans un autre encodage : il lit le fichier avec l'encodage d'entrée et écrit chaque caractère avec l'encodage de sortie, dans un nouveau fichier ou à la place de l'original. À placer avant un composant qui attend un encodage précis, ou pour livrer un fichier dans l'encodage demandé par un autre système. Rewrites a text file in another encoding: it reads the file with the input encoding and writes each character with the output encoding, to a new file or in place of the original. Put it before a component that expects a given encoding, or to deliver a file in the encoding another system asks for.

EntréeInput

Aucune : il commence son sous-job. Sinon un lien Iterate : un fichier par itération. None: it starts its subjob. Otherwise one Iterate link: one file per iteration.

SortieOutput

Aucune : ni flux de données, ni lien Iterate. Le résultat est le fichier écrit. None: no data flow, no Iterate link. The result is the written file.

Déclencheurs en sortieOutput triggers

On Subjob Ok On Subjob Error On Component Ok On Component Error Run if

UtilisationUsage

Convertir avant la lectureConvert before reading

OnSubjobOk row1 (Main) tChangeFileEncoding_1 tFileInputDelimited_1 tLogRow_1

Le tFileInputDelimited lit ensuite le fichier converti : son Encodage est l'encodage de sortie choisi ici. The tFileInputDelimited then reads the converted file: its Encoding is the output encoding chosen here.

Chaque fichier d'un dossierEach file of a folder

Iterate tFileList_1 tChangeFileEncoding_1

Nom du fichier d'entrée : ((String) globalMap.get("tFileList_1_CURRENT_FILEPATH")) ; nom de sortie construit à partir de CURRENT_FILE, dans un autre dossier. Input file name: ((String) globalMap.get("tFileList_1_CURRENT_FILEPATH")); output name built from CURRENT_FILE, in another folder.

  1. Déposez le tChangeFileEncoding depuis la famille Fichier › Gestion (ou Qualité de données) de la palette. Drop the tChangeFileEncoding from the File › Management (or Data Quality) family of the palette.
  2. Cochez Utiliser l'encodage d'entrée personnalisé et indiquez l'encodage du fichier tel qu'il est. Sans cette case, l'encodage par défaut de Java est pris (voir les exemples). Check Use Custom Input Encoding and give the encoding of the file as it is. Without this box, the Java default encoding is used (see the examples).
  3. Indiquez les deux fichiers, puis l'Encodage de sortie voulu. Set the two files, then the wanted Output Encoding.

Paramètres simplesBasic settings

Les libellés sont ceux de l'onglet Composant ; le nom technique, en gris, est celui du paramètre dans le fichier du job. Les encodages sont des expressions Java : le Studio propose ISO-8859-15, UTF-8, ou une valeur saisie ("windows-1252", context.encoding…). Labels are those of the Component tab; the technical name, in grey, is the parameter name in the job file. Encodings are Java expressions: the Studio offers ISO-8859-15, UTF-8, or a typed value ("windows-1252", context.encoding…).

ParamètreSetting DéfautDefault VisibleShown Description
Utiliser l'encodage d'entrée personnaliséUse Custom Input EncodingUSE_INENCODING NonNo ToujoursAlways Décochée, le fichier est lu avec l'encodage par défaut de Java, System.getProperty("file.encoding") : UTF-8 dans nos essais (Java 21), mais il dépend de la version de Java et des options de lancement. Cochez-la pour ne pas dépendre de la machine. Unchecked, the file is read with the Java default encoding, System.getProperty("file.encoding"): UTF-8 in our tests (Java 21), but it depends on the Java version and the launch options. Check it so as not to depend on the machine.
Encodage d'entréeInput EncodingINENCODING "ISO-8859-15" Encodage personnalisé cochéCustom encoding checked L'encodage du fichier d'entrée, tel qu'il est écrit sur le disque. Un mauvais choix ne donne pas d'erreur : les octets illisibles deviennent le caractère de remplacement U+FFFD (voir les exemples). The encoding of the input file, as it is written on disk. A wrong choice gives no error: unreadable bytes become the replacement character U+FFFD (see the examples).
Nom du fichier d'entréeInput File NameINFILE_NAME chemin par défaut + /in.csvdefault path + /in.csv ToujoursAlways Le fichier à convertir, en expression Java : "C:/data/in.csv", context.folder + "/in.csv". The file to convert, as a Java expression: "C:/data/in.csv", context.folder + "/in.csv".
Nom du fichier de sortieOutput File NameOUTFILE_NAME chemin par défaut + /out.csvdefault path + /out.csv ToujoursAlways Le fichier écrit, remplacé s'il existe. Si l'expression est écrite exactement comme celle du fichier d'entrée, le fichier est converti sur place (voir les exemples). The written file, replaced if it exists. If the expression is written exactly like the input file one, the file is converted in place (see the examples).
Encodage de sortieOutput EncodingENCODING "ISO-8859-15" ToujoursAlways L'encodage du fichier écrit. Un caractère qu'il ne peut pas représenter devient ?, sans erreur. The encoding of the written file. A character it cannot represent becomes ?, with no error.
Taille de la mémoire tamponBuffer SizeBUFFERSIZE 8192 ToujoursAlways Taille, en caractères, des tampons de lecture et d'écriture : une expression Java entière. Size, in characters, of the read and write buffers: an integer Java expression.

Paramètres avancésAdvanced settings

ParamètreSetting DéfautDefault VisibleShown Description
Créer le répertoire s'il n'existe pasCreate directory if does not existCREATE OuiYes ToujoursAlways Crée le dossier du fichier de sortie, avec ses parents. Décochée, un dossier absent arrête le composant (voir les erreurs). Creates the folder of the output file, with its parents. Unchecked, a missing folder stops the component (see the errors).

Variables globalesGlobal variables

Le composant déclare EXISTS et FILENAME, que le Studio propose dans la liste des variables, mais il ne les remplit pas : elles valent null. Il remplit à la place ISEND, absente de la liste. Un tJava relié par On Subjob Ok les affiche : The component declares EXISTS and FILENAME, which the Studio offers in the variable list, but it does not fill them: they are null. It fills ISEND instead, missing from the list. A tJava connected with On Subjob Ok prints them:

EXISTS Boolean
Déclarée, jamais remplie : null.Declared, never filled: null.
FILENAME String
Déclarée, jamais remplie : null. Le chemin du fichier écrit est celui de Nom du fichier de sortie.Declared, never filled: null. The path of the written file is the one of Output File Name.
ISEND Boolean
true une fois la conversion terminée ; absente si le composant a échoué avant.true once the conversion is done; absent if the component failed before.
System.out.println("EXISTS: " + globalMap.get("tChangeFileEncoding_1_EXISTS"));
System.out.println("FILENAME: " + globalMap.get("tChangeFileEncoding_1_FILENAME"));
System.out.println("ISEND: " + globalMap.get("tChangeFileEncoding_1_ISEND"));
EXISTS: null
FILENAME: null
ISEND: true

ExemplesExamples

Le fichier d'entrée utf8.txt contient une ligne, Café 10 €, en UTF-8. Les chemins sont écrits à partir de la variable de contexte folder. Un tJava relié par On Subjob Ok affiche les octets des fichiers, en hexadécimal ; les sorties sont celles de la console, copiées depuis une exécution du job. The utf8.txt input file holds one line, Café 10 €, in UTF-8. Paths are written from the folder context variable. A tJava connected with On Subjob Ok prints the bytes of the files, in hexadecimal; the outputs are the console ones, copied from a run of the job.

UTF-8 vers ISO-8859-15UTF-8 to ISO-8859-15

OnSubjobOk tChangeFileEncoding_1 tJava_1

Encodage d'entrée personnalisé "UTF-8" ; entrée context.folder + "/enc/utf8.txt" ; sortie context.folder + "/out/enc/latin15.txt" ; encodage de sortie "ISO-8859-15". Custom input encoding "UTF-8"; input context.folder + "/enc/utf8.txt"; output context.folder + "/out/enc/latin15.txt"; output encoding "ISO-8859-15".

for (String f : new String[] {"/enc/utf8.txt", "/out/enc/latin15.txt"}) {
    StringBuilder sb = new StringBuilder();
    for (byte b : java.nio.file.Files.readAllBytes(java.nio.file.Paths.get(context.folder + f))) {
        sb.append(String.format("%02X ", b));
    }
    System.out.println(f.substring(f.lastIndexOf('/') + 1) + ": " + sb.toString().trim());
}
utf8.txt: 43 61 66 C3 A9 20 31 30 20 E2 82 AC 0A
latin15.txt: 43 61 66 E9 20 31 30 20 A4 0A

é passe de deux octets (C3 A9) à un (E9), € de trois (E2 82 AC) à un (A4). La fin de ligne (0A) est gardée telle quelle. é goes from two bytes (C3 A9) to one (E9), € from three (E2 82 AC) to one (A4). The line end (0A) is kept as is.

Sans encodage d'entréeWithout input encoding

Même conversion, Utiliser l'encodage d'entrée personnalisé décoché. Le tJava affiche aussi l'encodage par défaut de Java : Same conversion, Use Custom Input Encoding unchecked. The tJava also prints the Java default encoding:

file.encoding: UTF-8
default.txt: 43 61 66 E9 20 31 30 20 A4 0A

Même résultat, parce que l'encodage par défaut était ici UTF-8, comme le fichier. Sur une machine où il est autre, le même job lit mal le fichier. Same result, because the default encoding was UTF-8 here, like the file. On a machine where it is different, the same job reads the file wrongly.

Caractère absent de l'encodage de sortieCharacter missing from the output encoding

Encodage de sortie "ISO-8859-1", qui n'a pas de € : Output encoding "ISO-8859-1", which has no €:

latin1.txt: 43 61 66 E9 20 31 30 20 3F 0A

€ est devenu ? (3F), sans erreur ni message. € became ? (3F), with no error or message.

Vers UTF-16To UTF-16

Encodage de sortie "UTF-16" : Output encoding "UTF-16":

utf16.txt: FE FF 00 43 00 61 00 66 00 E9 00 20 00 31 00 30 00 20 20 AC 00 0A

Java écrit une marque d'ordre des octets (FE FF) en tête, puis deux octets par caractère. "UTF-16LE" ou "UTF-16BE" n'en écrivent pas (d'après Java, non essayé ici). Java writes a byte order mark (FE FF) first, then two bytes per character. "UTF-16LE" or "UTF-16BE" do not write one (per Java, not tried here).

Sur placeIn place

Entrée et sortie : la même expression, context.folder + "/enc/inplace.txt" (une copie de utf8.txt), de UTF-8 vers ISO-8859-15. Le tJava affiche aussi le contenu du dossier enc. Input and output: the same expression, context.folder + "/enc/inplace.txt" (a copy of utf8.txt), from UTF-8 to ISO-8859-15. The tJava also prints the content of the enc folder.

inplace.txt: 43 61 66 E9 20 31 30 20 A4 0A
[bom.txt, inplace.txt, latin.txt, utf8.txt]

Le composant écrit d'abord dans inplace.txt_tmp, puis remplace l'original : il ne reste pas de fichier temporaire. Les deux expressions sont comparées comme du texte : écrites autrement, elles vident le fichier (voir les erreurs). The component first writes to inplace.txt_tmp, then replaces the original: no temporary file is left. The two expressions are compared as text: written differently, they empty the file (see the errors).

Mauvais encodage d'entréeWrong input encoding

latin.txt, la même ligne en ISO-8859-15, lue comme "UTF-8" et écrite en "UTF-8" : latin.txt, the same line in ISO-8859-15, read as "UTF-8" and written as "UTF-8":

latin.txt: 43 61 66 E9 20 31 30 20 A4 0A
wrong.txt: 43 61 66 EF BF BD 20 31 30 20 EF BF BD 0A

é et € sont perdus : chacun est remplacé par U+FFFD (EF BF BD, affiché �). Aucune erreur ne le signale. é and € are lost: each one is replaced with U+FFFD (EF BF BD, shown as �). No error reports it.

Fichier UTF-8 avec BOMUTF-8 file with BOM

bom.txt commence par la marque UTF-8 EF BB BF ; lu en "UTF-8", écrit en "ISO-8859-15" : bom.txt starts with the UTF-8 mark EF BB BF; read as "UTF-8", written as "ISO-8859-15":

bom.txt: EF BB BF 43 61 66 C3 A9 0A
bom.txt: 3F 43 61 66 E9 0A

La marque est lue comme un caractère, qui n'existe pas en ISO-8859-15 : le fichier converti commence par ?. The mark is read as a character, which does not exist in ISO-8859-15: the converted file starts with ?.

ErreursErrors

Le nom du job est remplacé par MyJob, le dossier de travail par C:\data ; les traces d'exception sont abrégées. La fin des messages vient de Windows, dans sa langue. The job name is replaced with MyJob, the working folder with C:\data; exception traces are shortened. The end of the messages comes from Windows, in its language.

Fichier d'entrée absentMissing input file

Entrée context.folder + "/enc/missing.txt", qui n'existe pas. Un tJava relié par On Component Error regarde le fichier de sortie : Input context.folder + "/enc/missing.txt", which does not exist. A tJava connected with On Component Error looks at the output file:

Exception in component tChangeFileEncoding_1 (MyJob)
java.io.FileNotFoundException: C:\data\enc\missing.txt (Le fichier spécifié est introuvable)
	at java.base/java.io.FileInputStream.open0(Native Method)
	…
missing_out.txt exists: true, 0 bytes

Le fichier de sortie est ouvert avant le fichier d'entrée : il a été créé, vide, et un ancien fichier du même nom est perdu. Testez l'entrée avant (tFileExist). The output file is opened before the input file: it was created, empty, and an old file with the same name is lost. Test the input first (tFileExist).

Dossier de sortie absentMissing output folder

Sortie context.folder + "/out/enc/new/x.txt", dossier new absent, Créer le répertoire s'il n'existe pas décoché : le job s'arrête (code 1). Output context.folder + "/out/enc/new/x.txt", new folder missing, Create directory if does not exist unchecked: the job stops (exit code 1).

Exception in component tChangeFileEncoding_1 (MyJob)
java.io.FileNotFoundException: C:\data\out\enc\new\x.txt (Le chemin d’accès spécifié est introuvable)
	at java.base/java.io.FileOutputStream.open0(Native Method)
	…

Même fichier, expressions différentes : fichier vidéSame file, different expressions: file emptied

Entrée context.folder + "/enc/inplace2.txt", sortie context.folder + "/enc/" + "inplace2.txt" : le même fichier, écrit autrement. Le tJava relié par On Subjob Ok affiche sa taille : Input context.folder + "/enc/inplace2.txt", output context.folder + "/enc/" + "inplace2.txt": the same file, written differently. The tJava connected with On Subjob Ok prints its size:

inplace2.txt: 0 bytes

Le mode « sur place » n'est pris que si les deux expressions sont identiques au caractère près. Sinon, le fichier de sortie est ouvert, donc vidé, avant la lecture : le contenu est perdu, sans erreur. Pour convertir un fichier sur place, recopiez exactement la même expression dans les deux champs. The “in place” mode is only taken if the two expressions are identical character for character. Otherwise, the output file is opened, so emptied, before the reading: the content is lost, with no error. To convert a file in place, copy exactly the same expression into both fields.

Conseils et limitesTips and limits

Aucune erreur d'encodageNo encoding error

Ni un mauvais encodage d'entrée, ni un caractère impossible en sortie n'arrêtent le composant : ils donnent U+FFFD ou ?. Pour vérifier une conversion, comparez le nombre de ? avant et après, ou relisez le fichier dans un tJava. Neither a wrong input encoding nor an impossible output character stops the component: they give U+FFFD or ?. To check a conversion, compare the number of ? before and after, or read the file back in a tJava.

BOM gardéeBOM kept

Une marque d'ordre des octets en tête du fichier d'entrée est recopiée comme un caractère. Vers un encodage d'un octet par caractère, elle devient ? en tête du fichier converti. Demandez si possible un fichier sans BOM à la source. A byte order mark at the start of the input file is copied as a character. To a one-byte-per-character encoding, it becomes ? at the start of the converted file. If possible, ask the source for a file without BOM.

Fichier entier, lignes intactesWhole file, lines untouched

Le composant recopie le texte par blocs de caractères, sans découper en lignes : les fins de ligne et le contenu restent les mêmes, seuls les octets changent. Le fichier n'est pas chargé en mémoire. The component copies the text in blocks of characters, without splitting into lines: line ends and content stay the same, only the bytes change. The file is not loaded in memory.

Lire sans convertirRead without converting

Pour seulement lire un fichier dans son encodage, la conversion n'est pas nécessaire : les composants de lecture (tFileInputDelimited…) ont leur propre paramètre Encodage. tChangeFileEncoding sert quand le fichier lui-même doit changer. To only read a file in its encoding, no conversion is needed: reading components (tFileInputDelimited…) have their own Encoding setting. tChangeFileEncoding is for when the file itself must change.

Voir aussiSee also