unova_factur_x 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a55d91791d062b326c0c4ae531507b4ad84a7249f3e1c7b8c1567040dddfb4c2
-  data.tar.gz: 5c38746bf64d6a103ffad89afa73b5bcf85478f14bdfdbe26508da2f09c03be6
+  metadata.gz: ea40c89024db0ae23f9c9ae3810842a3287fca547b7e71173cdad0a76484cef2
+  data.tar.gz: 8e7fa13a6e7231e3c45b54d3d79c295355712546aac6341e0d055ed05171fcf5
 SHA512:
-  metadata.gz: d44e83f78f0d4d4fa62dff23e05b3a696f2141da10dd5106bae8a0fe3f6f3c6a111832dd53632f054fb762032bf44c1d6f9d59f6c61dcf7b002404ba8d9523c2
-  data.tar.gz: a9988c5d634cfccc5e173a02e490f12c59a11a4c6cf644a2d2580af5c4b82e7ccaf9d358081a7faf1688bf4659f0729af9a4a49eb4eb78d8f899dcb1be2960cd
+  metadata.gz: a77cfcd8c5d379ed7db10607c23f992cc3e09d335b84a1bf3286611ef89b4997395ccfbde90e68f84ecde8672420d9a394d0b08f0b6e0dd2d6c293ba8e98da5d
+  data.tar.gz: 0bb7a2cbc4cd9bedc7ff7a5e69e1048fabde9484d91f1e45001fd558dc11df0bf02b3b9feb1c21693310c2400a651c2068488b1ae197a70fe295df2e3e1b3268

data/README.md

@@ -1,181 +1,194 @@
 # UnovaFacturX
 
-Gem permettant la génération de factures et d'avoirs au format Factur-X.
+Factur-X is a hybrid electronic invoice format with a human-readable PDF file that contains, as an attachment, a structured XML file.
+This gem allows you to transform invoices and credits notes from the PDF format to the Factur-X format.
 
-## Installation
+## Setup
 
-Ajouter la gem au gemfile et faire un ```bundle install```
+Add the gem to your gemfile and `bundle install`:
 ```ruby
-gem "unova_factur_x", git: "git@gitlab.unova.fr:unova-factur-x/unova-factur-x.git"
+gem "unova_factur_x"
 ```
+If you want to use the validator for the generated XML file of the Factur-X, you also need to have Java installed on your computer.
 
-## Utilisation
+## Usage
 
-Il suffit d'appeler la fonction generate de la gem à l'envoi du PDF par le controller avec les paramètres suivants :
-- pdf: Le fichier PDF de la facture/avoir à transformer en Factur-X. Prends en charge ces deux formes :
-  - Depuis un fichier :
+Simply call the `generate` method of the gem when you want to send the PDF to the user from your controller.
+The method accepts the following parameters:
+- pdf: The PDF file of the invoice/credit note to transform to Factur-X. It can be provided in two ways:
+  - From a file:
     ```ruby
     path = ActiveStorage::Blob.service.send(:path_for, @invoice.file.key)
     pdf = File.open(path, 'rb')
     ```
-  - Depuis une génération Prawn :
+  - From a Prawn-generated PDF:
     ```ruby
-    pdf = DocumentPdf.new(**options).render
+    pdf = PdfDocument.new(**options).render
     ```
-- document_hash: Le hash d'entrée pour la génération du XML, voir ci-après pour plus de détails.
-- [optionnel] type: Le type de document (:invoice par défaut):
-  - :invoice pour une facture,
-  - :credit pour un avoir,
-- [optionnel] with_validations: true ou false, si à true, va essayer de valider les données du hash fourni pour Factur-X /!\ Nécessite Java, à désactiver si Java non présent /!\ (true par défaut)
-- [optionnel] devise: pour configurer la monnaie utilisée sur la facture/l'avoir (Euros 'EUR' par défaut).
+- document_hash: The hash required to generate the XML part of the Factur-X. See below for more details.
+- [optional] type: The document type:
+  - `:invoice` for an invoice (default value),
+  - `:credit` for a credit note,
+- [optional] with_validations: `true` or `false`, default as `true`. If true, the generated XML file will be checked using the validator. **WARNING: Java is required for this to work**
+- [optional] currency: To configure the used currency (Default is euros 'EUR').
 ```ruby
-# Exemple d'utilisation :
-send_data UnovaFacturX.generate(pdf: pdf, document_hash: document_hash, type: :invoice, with_validations: true, devise: "USD"),
+# Usage example:
+send_data UnovaFacturX.generate(pdf: pdf, document_hash: document_hash, type: :invoice, with_validations: true, currency: "USD"),
           filename: "Factur-X.pdf",
           type: 'application/pdf',
           disposition: 'attachment'
 ```
 
-Pour le hash du document attendu :
-- Les montants fournis doivent être arithmétiquement cohérents, aucune correction automatique n’est effectuée.
-- Tous les attributs de la facture/du crédit sont attendus en String.
-- Respecter la forme ci-dessous :
+### Document hash structure overview
+
+
+For the expected document hash:
+- The document hash is a structured Ruby hash composed of the following main sections:
+  - `seller`
+  - `buyer`
+  - `items`
+  - `payment_means`
+  - `vat_breakdown`
+  - `totals`
+- Provided amounts must be arithmetically consistent; no automatic correction is performed.
+- All attributes must be provided as strings.
+- Follow the structure below:
 ```ruby
-# Exemple de hash pour une facture (Même chose pour un avoir /!\ Ne pas mettre les valeurs de l'avoir en négatif /!\) :
+# Example hash for an invoice (the same applies to a credit note; IMPORTANT: do not use negative values for credit note):
 document_hash = {
-    id: "Numéro unique de facture (BT-1) [OBLIGATOIRE]",
-    issue_date: "Date d'émission format YYYYMMDD (BT-2) [OBLIGATOIRE]",
-    
-    seller: {
-      name: "Nom légal du vendeur (BT-27) [OBLIGATOIRE]",
-      legal_id: "Identifiant légal (SIREN/SIRET) (BT-30) [OPTIONNEL]",
-      vat_number: "Numéro TVA avec préfixe pays acheteur (ex: FR123...) (BT-31) [OPTIONNEL]",
-      address: {
-        line1: "Rue (BT-35) [OBLIGATOIRE]",
-        line2: "Complément adresse [OPTIONNEL]",
-        postcode: "Code postal (BT-38) [OBLIGATOIRE]",
-        city: "Ville (BT-37) [OBLIGATOIRE]",
-        country: "Code pays ISO 3166-1 alpha-2 (BT-40) [OBLIGATOIRE]",
-      }
+  id: "Unique invoice number (BT-1) [REQUIRED]",
+  issue_date: "Issue date in YYYYMMDD format (BT-2) [REQUIRED]",
+
+  seller: {
+    name: "Seller legal name (BT-27) [REQUIRED]",
+    legal_id: "Legal identifier (SIREN/SIRET) (BT-30) [OPTIONAL]",
+    vat_number: "VAT number including buyer country prefix (e.g. FR123...) (BT-31) [OPTIONAL]",
+    address: {
+      line1: "Street address (BT-35) [REQUIRED]",
+      line2: "Address complement [OPTIONAL]",
+      postcode: "Postal code (BT-38) [REQUIRED]",
+      city: "City (BT-37) [REQUIRED]",
+      country: "ISO 3166-1 alpha-2 country code (BT-40) [REQUIRED]",
+    }
+  },
+
+  # [REQUIRED BLOCK]
+  buyer: {
+    id: "Internal customer identifier (BT-46) [OPTIONAL]",
+    name: "Customer legal name (BT-44) [REQUIRED]",
+    vat_number: "VAT number including buyer country prefix (e.g. FR123...) (BT-48) [OPTIONAL]",
+    contact: { # [OPTIONAL]
+               name: "Customer contact name (BT-56) [OPTIONAL]",
     },
-    
-    # [BLOC OBLIGATOIRE]
-    buyer: {
-      id: "Identifiant interne client (BT-46) [OPTIONNEL]",
-      name: "Nom légal du client (BT-44) [OBLIGATOIRE]",
-      vat_number: "Numéro TVA avec préfixe pays acheteur (ex: FR123...) (BT-48) [OPTIONNEL]",
-      contact: { # [OPTIONNEL]
-        name: "Nom du contact client (BT-56) [OPTIONNEL]",
+    address: {
+      line1: "Street address (BT-50) [REQUIRED]",
+      line2: "Address complement [OPTIONAL]",
+      postcode: "Postal code (BT-53) [REQUIRED]",
+      city: "City (BT-52) [REQUIRED]",
+      country: "ISO 3166-1 alpha-2 country code (BT-55) [REQUIRED]",
+    }
+  },
+
+  # [OPTIONAL BLOCK]
+  delivery: {
+    gln: "GLN identifier (schemeID 0088) (BT-71) [OPTIONAL]",
+    gln_scheme: "0088: GLN (GS1), 0002: SIRENE (France), 9906: SIRET, 9915: French intra-community VAT, 0060: DUNS [OPTIONAL | REQUIRED IF GLN IS PROVIDED]",
+    date: "Actual delivery date in YYYYMMDD format (BT-72) [OPTIONAL]",
+    address: {
+      line1: "Delivery street address (BT-75) [OPTIONAL]",
+      line2: "Delivery address complement [OPTIONAL]",
+      postcode: "Delivery postal code (BT-75) [OPTIONAL]",
+      city: "Delivery city (BT-74) [OPTIONAL]",
+      country: "ISO 3166-1 alpha-2 country code (BT-76) [OPTIONAL]",
+    }
+  },
+
+  # [REQUIRED BLOCK] (minimum 1 item)
+  items: [
+    {
+      line_id: "Line number (BT-126) [REQUIRED]",
+      seller_assigned_id: "Internal product identifier (BT-155) [OPTIONAL]",
+      name: "Product/service description (BT-153) [REQUIRED]",
+      quantity: "Quantity (BT-129) [REQUIRED]",
+      unit_code: "UN/ECE Rec20 unit code (e.g. H87, C62, DAY) (BT-130) [REQUIRED]",
+      price_ht: "Net unit price excluding VAT (BT-146) [REQUIRED]",
+      vat_rate: "VAT rate (BT-152) [REQUIRED]",
+      vat_category: "VAT category (S, Z, E, AE...) (BT-151) [REQUIRED]",
+      discount: { # [OPTIONAL]
+        total_amount: "Discount amount applicable to the invoice line (BT-136) [OPTIONAL unless discount block is present]",
+        percentage: "Discount percentage applicable to the invoice line (BT-138) [OPTIONAL unless discount block is present]",
+        # reason OR reason_code [REQUIRED] if block is present
+        reason: "Reason for the invoice line discount (BT-139) [OPTIONAL unless discount block is present]",
+        reason_code: "Reason code for the invoice line discount (BT-140) [OPTIONAL unless discount block is present]"
       },
-      address: {
-        line1: "Rue (BT-50) [OBLIGATOIRE]",
-        line2: "Complément adresse [OPTIONNEL]",
-        postcode: "Code postal (BT-53) [OBLIGATOIRE]",
-        city: "Ville (BT-52) [OBLIGATOIRE]",
-        country: "Code pays ISO 3166-1 alpha-2 (BT-55) [OBLIGATOIRE]",
-      }
-    },
-    
-    # [BLOC OPTIONNEL]
-    delivery: {
-      gln: "Identifiant GLN (schemeID 0088) (BT-71) [OPTIONNEL]",
-      gln_scheme: "0088: GLN (GS1), 0002: SIRENE (France), 9906: SIRET, 9915: TVA intracom FR, 0060: DUNS [OPTIONNEL | OBLIGATOIRE SI GLN]",
-      date: "Date réelle de livraison format YYYYMMDD (BT-72) [OPTIONNEL]",
-      address: {
-        line1: "Rue livraison (BT-75) [OPTIONNEL]",
-        line2: "Complément adresse livraison [OPTIONNEL]",
-        postcode: "Code postal livraison (BT-75) [OPTIONNEL]",
-        city: "Ville livraison (BT-74) [OPTIONNEL]",
-        country: "Code pays ISO 3166-1 alpha-2 (BT-76) [OPTIONNEL]",
-      }
-    },
-    
-    # [BLOC OBLIGATOIRE] (minimum 1 item)
-    items: [
-      {
-        line_id: "Numéro de ligne (BT-126) [OBLIGATOIRE]",
-        seller_assigned_id: "Identifiant interne produit (BT-155) [OPTIONNEL]",
-        name: "Désignation produit/service (BT-153) [OBLIGATOIRE]",
-        quantity: "Quantité (BT-129) [OBLIGATOIRE]",
-        unit_code: "Code unité UN/ECE Rec20 (ex: H87, C62, DAY) (BT-130) [OBLIGATOIRE]",
-        price_ht: "Prix unitaire net HT (BT-146) [OBLIGATOIRE]",
-        vat_rate: "Taux TVA (BT-152) [OBLIGATOIRE]",
-        vat_category: "Catégorie TVA (S, Z, E, AE...) (BT-151) [OBLIGATOIRE]",
-        discount: { # [OPTIONNEL]
-          total_amount: "Montant de la remise applicable à la ligne de facture (BT-136) [OPTIONNEL sauf si discount]",
-          percentage: "Pourcentage de remise applicable à la ligne de facture (BT-138) [OPTIONNEL sauf si discount]",
-          # reason OU reason_code [OBLIGATOIRE] si bloc présent
-          reason: "Motif de la remise applicable à la ligne de facture (BT-139) [OPTIONNEL sauf si discount]",
-          reason_code: "Code de motif de la remise applicable à la ligne de facture (BT-140) [OPTIONNEL sauf si discount]"
-        },
-        line_total: "Montant net de la ligne HT = Quantité × Prix unitaire net (BT-131)"
-      }
-    ],
-    
-    # [BLOC OBLIGATOIRE]
-    payment_means: {
-      type_code: "Code UNCL 4461 (30 = virement) (BT-81) [OBLIGATOIRE]",
-      iban: "IBAN bénéficiaire (BT-84) [OBLIGATOIRE si virement]",
-    },
-    
-    # [BLOC OBLIGATOIRE]
-    vat_breakdown: [
-      {
-        vat_category: "Catégorie TVA (BT-118) [OBLIGATOIRE]",
-        vat_rate: "Taux TVA % (BT-119) [OBLIGATOIRE]",
-        taxable_amount: "Base HT pour ce taux (BT-116) [OBLIGATOIRE]",
-        tax_amount: "Montant TVA pour ce taux (BT-117) [OBLIGATOIRE]",
-        # exemption_reason OU exemption_reason_code [OBLIGATOIRE] si vat_category = "E" (Exempt)
-        exemption_reason: "Motif d'exonération de la TVA (BT-120)",
-        exemption_reason_code: "Code de motif d'exonération de la TVA (BT-121)"
-      }
-    ],
-    
-    # [BLOC OPTIONNEL]
-    discount: [ # Ce bloc est un tableau avec un item par taux de TVA d'item. Il doit donc avoir la même longueur que le bloc vat_breakdown
-      {
-        vat_category: "Catégorie TVA (BT-118) [OBLIGATOIRE si le bloc est présent]",
-        vat_rate: "Taux TVA % (BT-119) [OBLIGATOIRE si le bloc est présent]",
-        total_amount: "Montant total de la remise pour le taux de TVA [OBLIGATOIRE si percentage présent]",
-        percentage: "% de remise au niveau du document si la remise est en % (BT-94) [OPTIONNEL]",
-        # reason OU reason_code [OBLIGATOIRE] si bloc présent
-        reason: "Motif de la remise au niveau du document (BT-97)",
-        reason_code: "Code de motif de la remise au niveau du document (BT-98)",
-      }
-    ],
-    
-    # [BLOC OBLIGATOIRE]
-    totals: {
-      line_total_ht: "Total HT lignes (BT-106) [OBLIGATOIRE]",
-      total_discount: "Somme des remises au niveau du document (BT-107) [OBLIGATOIRE si bloc discount présent]",
-      tax_basis_total_ht: "Total bases taxables (BT-109) [OBLIGATOIRE]",
-      tax_total: "Total TVA (BT-110) [OBLIGATOIRE]",
-      grand_total_ttc: "Total TTC (BT-112) [OBLIGATOIRE]",
-      amount_due: "Montant à payer (BT-115) [OPTIONNEL]",
-      # due_date OU description [OBLIGATOIRE] si amount_due est défini et positif
-      due_date: "Date due du paiement format YYYYMMDD (BT-9)",
-      description: "Termes du paiement (BT-20)"
+      line_total: "Net line amount excluding VAT = Quantity × Net unit price (BT-131)"
+    }
+  ],
+
+  # [REQUIRED BLOCK]
+  payment_means: {
+    type_code: "UNCL 4461 code (30 = bank transfer) (BT-81) [REQUIRED]",
+    iban: "Beneficiary IBAN (BT-84) [REQUIRED for bank transfer]",
+  },
+
+  # [REQUIRED BLOCK]
+  vat_breakdown: [
+    {
+      vat_category: "VAT category (BT-118) [REQUIRED]",
+      vat_rate: "VAT rate % (BT-119) [REQUIRED]",
+      taxable_amount: "Taxable amount excluding VAT for this rate (BT-116) [REQUIRED]",
+      tax_amount: "VAT amount for this rate (BT-117) [REQUIRED]",
+      # exemption_reason OR exemption_reason_code [REQUIRED] if vat_category = 'E' (Exempt)
+      exemption_reason: "VAT exemption reason (BT-120)",
+      exemption_reason_code: "VAT exemption reason code (BT-121)"
+    }
+  ],
+
+  # [OPTIONAL BLOCK]
+  discount: [ # This block is an array with one item per item VAT rate. Therefore, it must have the same length as the vat_breakdown block.
+    {
+      vat_category: "VAT category (BT-118) [REQUIRED if block is present]",
+      vat_rate: "VAT rate % (BT-119) [REQUIRED if block is present]",
+      total_amount: "Total discount amount for the VAT rate [REQUIRED if percentage is present]",
+      percentage: "Document-level discount percentage if the discount is expressed as a percentage (BT-94) [OPTIONAL]",
+      # reason OR reason_code [REQUIRED] if block is present
+      reason: "Reason for the document-level discount (BT-97)",
+      reason_code: "Reason code for the document-level discount (BT-98)",
     }
+  ],
+
+  # [REQUIRED BLOCK]
+  totals: {
+    line_total_ht: "Total line amount excluding VAT (BT-106) [REQUIRED]",
+    total_discount: "Sum of document-level discounts (BT-107) [REQUIRED if discount block is present]",
+    tax_basis_total_ht: "Total taxable amount (BT-109) [REQUIRED]",
+    tax_total: "Total VAT amount (BT-110) [REQUIRED]",
+    grand_total_ttc: "Grand total including VAT (BT-112) [REQUIRED]",
+    amount_due: "Amount due for payment (BT-115) [OPTIONAL]",
+    # due_date OR description [REQUIRED] if amount_due is defined and positive
+    due_date: "Payment due date in YYYYMMDD format (BT-9)",
+    description: "Payment terms (BT-20)"
+  }
 }
 ```
 
-## Composants tiers
+## Third-Party Components
 
-Cette gem embarque les composants suivants :
+This gem includes the following third-party component:
 
-- Saxon-HE (processeur XSLT et XQuery) développé par Saxonica Limited, sous licence Mozilla Public License 2.0 (MPL-2.0).
+- Saxon-HE (XSLT and XQuery processor), developed by Saxonica Limited and licensed under the Mozilla Public License 2.0 (MPL-2.0).
 
-Le JAR Saxon-HE est redistribué tel quel et reste soumis à sa licence d’origine.
-Une copie de la licence MPL-2.0 est incluse dans ce repository sous le dossier LICENSES.
+The Saxon-HE JAR is redistributed as-is and remains subject to its original license terms.
+A copy of the MPL-2.0 license is included in this repository under the LICENSES directory.
 
-## Licence
+## License
 
-Ce projet est sous licence Apache 2.0.
+This project is licensed under the Apache License 2.0.
 
-La licence Apache 2.0 autorise l'utilisation, la modification, la distribution et la commercialisation du logiciel, à condition de conserver les mentions de droits d'auteur et de respecter les termes de la licence.
+The Apache License 2.0 permits the use, modification, distribution, and commercialization of the software, provided that copyright notices are retained and the terms of the license are respected.
 
-Sauf disposition contraire prévue par la loi ou convenue par écrit, ce logiciel est distribué « en l'état », sans garantie ni condition d'aucune sorte, expresse ou implicite.
+Unless required by applicable law or agreed to in writing, this software is distributed on an "AS IS" basis, without warranties or conditions of any kind, either express or implied.
 
-Pour consulter l'intégralité des conditions, reportez-vous au fichier `LICENSE` situé à la racine du dépôt ou au texte officiel : https://www.apache.org/licenses/LICENSE-2.0
+For the full license terms, refer to the LICENSE file located at the root of the repository or to the official license text: https://www.apache.org/licenses/LICENSE-2.0
 
-Copyright (C) UNOVA
+Copyright (c) 2026 UNOVA

data/THIRD-PARTY_COMPONENTS.txt

@@ -0,0 +1,29 @@
+NOTICE AND INFORMATION ABOUT THIRD-PARTY SOFTWARE
+
+This project includes third-party software components.
+
+------------------------------------------------------------
+1. Saxon-HE (XSLT and XQuery processor)
+------------------------------------------------------------
+
+Name: Saxon-HE
+Version: 12.4
+Author: Saxonica Limited
+Official website: https://www.saxonica.com/
+
+License: Mozilla Public License 2.0 (MPL-2.0)
+
+Copyright:
+Copyright (c) Saxonica Limited
+
+Saxon-HE is included in this distribution as a precompiled JAR file and remains subject to its original license terms.
+
+The full text of the MPL-2.0 license is available here:
+https://www.mozilla.org/en-US/MPL/2.0/
+
+A copy of the MPL-2.0 license is included in this project:
+LICENSES/MPL-2.0.txt
+
+------------------------------------------------------------
+END OF NOTICE
+------------------------------------------------------------

data/lib/unova_factur_x/factur_x_generator.rb

@@ -6,7 +6,7 @@ module UnovaFacturX
     end
 
     def call
-      # Override règles de base HexaPDF pour pas qu'il force la version en 2.0
+      # Override HexaPDF default rules to prevent it from forcing PDF version 2.0
       begin
         ::HexaPDF::Type::Catalog.send(:remove_field, :AF)
       rescue StandardError
@@ -14,20 +14,20 @@ module UnovaFacturX
       end
       ::HexaPDF::Type::Catalog.define_field :AF, type: ::HexaPDF::PDFArray
 
-      # Génération du XML grace au services (hash + xml)
+      # Generate the XML using the generator
       xml_doc = @xml
       xml_string = xml_doc.to_xml
       xml_io = StringIO.new(xml_string)
 
-      # Transformation du PDF en StringIO
+      # Convert the PDF into a StringIO object
       pdf_io = @pdf.is_a?(File) ? @pdf : StringIO.new(@pdf)
       pdf_io.rewind
 
-      # Création d'un nouveau PDF avec HexaPDF
+      # Create a new PDF using HexaPDF
       doc = ::HexaPDF::Document.new(io: pdf_io)
       doc.task(:pdfa, level: "3b") # PDF format A/3
 
-      # Ajout du XML au PDF
+      # Attach the XML file to the PDF
       file_spec = doc.files.add(
         xml_io,
         name: "factur-x.xml",
@@ -39,16 +39,16 @@ module UnovaFacturX
       doc.catalog[:AF] ||= []
       doc.catalog[:AF] << file_spec
 
-      # Réécriture des Metadata pour correspondre à Factur-X
+      # Rewrite the metadata to comply with Factur-X requirements
       doc.metadata.custom_metadata(metadata_xml)
 
-      # Renvoi du PDF en StringIO
+      # Return the PDF as a StringIO object
       doc.write_to_string
     end
 
     private
 
-    def metadata_xml # TODO : Utiliser les bonnes valeurs
+    def metadata_xml # TODO : Use invoice values
       <<~XML
         <rdf:Description rdf:about=""
                          xmlns:pdfaExtension="http://www.aiim.org/pdfa/ns/extension/"

data/lib/unova_factur_x/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UnovaFacturX
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

data/lib/unova_factur_x/xml_generator.rb

@@ -1,147 +1,14 @@
 module UnovaFacturX
   class XmlGenerator
-    # Générateur de fichiers XML de type CrossIndustryInvoice pour facture électronique
+    # @param document [Hash] A hash representing an invoice or a credit note.
+    # @param type [Symbol] Document type: :invoice for a standard invoice, :credit for a credit note (:invoice by default).
+    # @param currency [String] ISO 4217 currency code.
     #
-    # Cette classe permet de générer dynamiquement un fichier XML structuré selon le standard CII (EN16931), à partir d'un objet ruby.
-    # Elle supporte les factures simples (type 380) ainsi que les avoirs (type 381).
-    # Les montants fournis doivent être arithmétiquement cohérents, aucune correction automatique n’est effectuée.
-    # Aussi, pour plus de simplicité, tous les attributs de la facture/du crédit sont attendus en String.
-    # @example
-    #   # Générer un XML de facture standard
-    #   xml = XmlGenerator.new(invoice).call
-    #
-    #   # Générer un XML pour un avoir
-    #   xml = XmlGenerator.new(credit, type: :credit).call
-    #
-    #   # Configurer la monnaie utilisée sur la facture
-    #   xml = XmlGenerator.new(invoice, devise: "USD") # 'EUR' par défaut
-    #
-    #   # Exemple de hash pour une facture (Même chose pour un avoir /!\ Ne pas mettre les valeurs de l'avoir en négatif /!\) :
-    #   document = {
-    #     id: "Numéro unique de facture (BT-1) [OBLIGATOIRE]",
-    #     issue_date: "Date d'émission format YYYYMMDD (BT-2) [OBLIGATOIRE]",
-    #
-    #     seller: {
-    #       name: "Nom légal du vendeur (BT-27) [OBLIGATOIRE]",
-    #       legal_id: "Identifiant légal (SIREN/SIRET) (BT-30) [OPTIONNEL]",
-    #       vat_number: "Numéro TVA avec préfixe pays acheteur (ex: FR123...) (BT-31) [OPTIONNEL]",
-    #       address: {
-    #         line1: "Rue (BT-35) [OBLIGATOIRE]",
-    #         line2: "Complément adresse [OPTIONNEL]",
-    #         postcode: "Code postal (BT-38) [OBLIGATOIRE]",
-    #         city: "Ville (BT-37) [OBLIGATOIRE]",
-    #         country: "Code pays ISO 3166-1 alpha-2 (BT-40) [OBLIGATOIRE]",
-    #       }
-    #     },
-    #
-    #     # [BLOC OBLIGATOIRE]
-    #     buyer: {
-    #       id: "Identifiant interne client (BT-46) [OPTIONNEL]",
-    #       name: "Nom légal du client (BT-44) [OBLIGATOIRE]",
-    #       vat_number: "Numéro TVA avec préfixe pays acheteur (ex: FR123...) (BT-48) [OPTIONNEL]",
-    #       contact: { # [OPTIONNEL]
-    #         name: "Nom du contact client (BT-56) [OPTIONNEL]",
-    #       },
-    #       address: {
-    #         line1: "Rue (BT-50) [OBLIGATOIRE]",
-    #         line2: "Complément adresse [OPTIONNEL]",
-    #         postcode: "Code postal (BT-53) [OBLIGATOIRE]",
-    #         city: "Ville (BT-52) [OBLIGATOIRE]",
-    #         country: "Code pays ISO 3166-1 alpha-2 (BT-55) [OBLIGATOIRE]",
-    #       }
-    #     },
-    #
-    #     # [BLOC OPTIONNEL]
-    #     delivery: {
-    #       gln: "Identifiant GLN (schemeID 0088) (BT-71) [OPTIONNEL]",
-    #       gln_scheme: "0088: GLN (GS1), 0002: SIRENE (France), 9906: SIRET, 9915: TVA intracom FR, 0060:	DUNS [OPTIONNEL | OBLIGATOIRE SI GLN]",
-    #       date: "Date réelle de livraison format YYYYMMDD (BT-72) [OPTIONNEL]",
-    #       address: {
-    #         line1: "Rue livraison (BT-75) [OPTIONNEL]",
-    #         line2: "Complément adresse livraison [OPTIONNEL]",
-    #         postcode: "Code postal livraison (BT-75) [OPTIONNEL]",
-    #         city: "Ville livraison (BT-74) [OPTIONNEL]",
-    #         country: "Code pays ISO 3166-1 alpha-2 (BT-76) [OPTIONNEL]",
-    #       }
-    #     },
-    #
-    #     # [BLOC OBLIGATOIRE] (minimum 1 item)
-    #     items: [
-    #       {
-    #         line_id: "Numéro de ligne (BT-126) [OBLIGATOIRE]",
-    #         seller_assigned_id: "Identifiant interne produit (BT-155) [OPTIONNEL]",
-    #         name: "Désignation produit/service (BT-153) [OBLIGATOIRE]",
-    #         quantity: "Quantité (BT-129) [OBLIGATOIRE]",
-    #         unit_code: "Code unité UN/ECE Rec20 (ex: H87, C62, DAY) (BT-130) [OBLIGATOIRE]",
-    #         price_ht: "Prix unitaire net HT (BT-146) [OBLIGATOIRE]",
-    #         vat_rate: "Taux TVA (BT-152) [OBLIGATOIRE]",
-    #         vat_category: "Catégorie TVA (S, Z, E, AE...) (BT-151) [OBLIGATOIRE]",
-    #         discount: { # [OPTIONNEL]
-    #           total_amount: "Montant de la remise applicable à la ligne de facture (BT-136) [OPTIONNEL sauf si discount]",
-    #           percentage: "Pourcentage de remise applicable à la ligne de facture (BT-138) [OPTIONNEL sauf si discount]",
-    #           # reason OU reason_code [OBLIGATOIRE] si bloc présent
-    #           reason: "Motif de la remise applicable à la ligne de facture (BT-139) [OPTIONNEL sauf si discount]",
-    #           reason_code: "Code de motif de la remise applicable à la ligne de facture (BT-140) [OPTIONNEL sauf si discount]"
-    #         }
-    #         line_total: "Montant net de la ligne HT = Quantité × Prix unitaire net (BT-131)"
-    #       }
-    #     ],
-    #
-    #     # [BLOC OBLIGATOIRE]
-    #     payment_means: {
-    #       type_code: "Code UNCL 4461 (30 = virement) (BT-81) [OBLIGATOIRE]",
-    #       iban: "IBAN bénéficiaire (BT-84) [OBLIGATOIRE si virement]",
-    #     },
-    #
-    #     # [BLOC OBLIGATOIRE]
-    #     vat_breakdown: [
-    #       {
-    #         vat_category: "Catégorie TVA (BT-118) [OBLIGATOIRE]",
-    #         vat_rate: "Taux TVA % (BT-119) [OBLIGATOIRE]",
-    #         taxable_amount: "Base HT pour ce taux (BT-116) [OBLIGATOIRE]",
-    #         tax_amount: "Montant TVA pour ce taux (BT-117) [OBLIGATOIRE]",
-    #         # exemption_reason OU exemption_reason_code [OBLIGATOIRE] si vat_category = "E" (Exempt)
-    #         exemption_reason: "Motif d'exonération de la TVA (BT-120)",
-    #         exemption_reason_code: "Code de motif d'exonération de la TVA (BT-121)"
-    #       }
-    #     ],
-    #
-    #     # [BLOC OPTIONNEL]
-    #     discount: [ # Ce bloc est un tableau avec un item par taux de TVA d'item. Il doit donc avoir la même longueur que le bloc vat_breakdown
-    #       {
-    #         vat_category: "Catégorie TVA (BT-118) [OBLIGATOIRE si le bloc est présent]",
-    #         vat_rate: "Taux TVA % (BT-119) [OBLIGATOIRE si le bloc est présent]",
-    #         total_amount: "Montant total de la remise pour le taux de TVA [OBLIGATOIRE si percentage présent]",
-    #         percentage: "% de remise au niveau du document si la remise est en % (BT-94) [OPTIONNEL]",
-    #         # reason OU reason_code [OBLIGATOIRE] si bloc présent
-    #         reason: "Motif de la remise au niveau du document (BT-97)",
-    #         reason_code: "Code de motif de la remise au niveau du document (BT-98)",
-    #       }
-    #     ],
-    #
-    #     # [BLOC OBLIGATOIRE]
-    #     totals: {
-    #       line_total_ht: "Total HT lignes (BT-106) [OBLIGATOIRE]",
-    #       total_discount: "Somme des remises au niveau du document (BT-107) [OBLIGATOIRE si bloc discount présent]",
-    #       tax_basis_total_ht: "Total bases taxables (BT-109) [OBLIGATOIRE]",
-    #       tax_total: "Total TVA (BT-110) [OBLIGATOIRE]",
-    #       grand_total_ttc: "Total TTC (BT-112) [OBLIGATOIRE]",
-    #       amount_due: "Montant à payer (BT-115) [OPTIONNEL]",
-    #       # due_date OU description [OBLIGATOIRE] si amount_due est défini et positif
-    #       due_date: "Date due du paiement format YYYYMMDD (BT-9)",
-    #       description: "Termes du paiement (BT-20)"
-    #     }
-    #   }
-    #
-    # @param document [Hash] Un hash représentant une facture ou un crédit.
-    # @param type [Symbol] Type de document : `:invoice` pour une facture normale, `:credit` pour un avoir. (`:invoice` par défaut)
-    # @param devise [String] Code ISO 4217
-    #
-    # @return [Nokogiri::XML::Document] Le document XML généré
-    def initialize(document, type: :invoice, devise: "EUR", validate: true)
+    # @return [Nokogiri::XML::Document] The generated XML document
+    def initialize(document, type: :invoice, currency: "EUR", validate: true)
       @document = document
       @type = type
-      @devise = devise
+      @currency = currency
       @validate = validate
     end
 
@@ -161,7 +28,7 @@ module UnovaFacturX
 
       validate_with_xslt!(builder.doc) if @validate
 
-      # Retourne le XML
+      # Returns the XML document
       builder.doc
     end
 
@@ -170,18 +37,18 @@ module UnovaFacturX
     def build_exchanged_document_context(xml)
       xml['rsm'].ExchangedDocumentContext do
         xml['ram'].GuidelineSpecifiedDocumentContextParameter do
-          xml['ram'].ID("urn:cen.eu:en16931:2017") # Identifiant du type de facture (Ici la norme Européenne)
+          xml['ram'].ID("urn:cen.eu:en16931:2017") # Identifier of the invoice specification (European EN16931 standard)
         end
       end
     end
 
     def build_exchanged_document(xml)
       xml['rsm'].ExchangedDocument do
-        xml['ram'].ID(@document[:id]) # Numéro de la facture BT-1 (Doit être unique/vendeur)
-        xml['ram'].TypeCode(@type == :credit ? "381" : "380") # Type de document (380 = facture, 381 = avoir) (BT-3)
+        xml['ram'].ID(@document[:id]) # Invoice number (BT-1) - must be unique per seller
+        xml['ram'].TypeCode(@type == :credit ? "381" : "380") # Document type (380 = invoice, 381 = credit note) (BT-3)
         if @document[:issue_date].present?
           xml['ram'].IssueDateTime do
-            xml['udt'].DateTimeString(@document[:issue_date], format: "102") # Date d’émission de la facture, format YYYYMMDD (BT-2)
+            xml['udt'].DateTimeString(@document[:issue_date], format: "102") # Invoice issue date in YYYYMMDD format (BT-2)
           end
         end
       end
@@ -197,47 +64,47 @@ module UnovaFacturX
     end
 
     def build_line_items(xml)
-      raise StandardError, "Besoin d'au moins un item" if @document[:items].blank?
+      raise StandardError, "At least one item is required" if @document[:items].blank?
 
       @document[:items].each do |item|
         xml['ram'].IncludedSupplyChainTradeLineItem do
           xml['ram'].AssociatedDocumentLineDocument do
-            xml['ram'].LineID(item[:line_id]) # Numéro de la ligne (BT-126)
+            xml['ram'].LineID(item[:line_id]) # Line number (BT-126)
           end
           xml['ram'].SpecifiedTradeProduct do
-            xml['ram'].SellerAssignedID(item[:seller_assigned_id]) if item[:seller_assigned_id].present? # Identifiant interne du produit attribué par le vendeur (BT-155)
-            xml['ram'].Name(item[:name]) # Désignation du produit/service (BT-153)
+            xml['ram'].SellerAssignedID(item[:seller_assigned_id]) if item[:seller_assigned_id].present? # Internal product identifier assigned by the seller (BT-155)
+            xml['ram'].Name(item[:name]) # Product/service description (BT-153)
           end
           xml['ram'].SpecifiedLineTradeAgreement do
             xml['ram'].NetPriceProductTradePrice do
-              xml['ram'].ChargeAmount(item[:price_ht]) # Prix unitaire net HT hors remise (BT-146)
+              xml['ram'].ChargeAmount(item[:price_ht]) # Net unit price excluding VAT (BT-146)
             end
           end
           xml['ram'].SpecifiedLineTradeDelivery do
-            xml['ram'].BilledQuantity(item[:quantity], unitCode: item[:unit_code]) # Quantité facturée (BT-129) avec code unité de mesure UN/ECE Rec.20/21 (BT-130)
+            xml['ram'].BilledQuantity(item[:quantity], unitCode: item[:unit_code]) # Quantity invoiced (BT-129) with unit code UN/ECE Rec. 20 (BT-130)
           end
 
           xml['ram'].SpecifiedLineTradeSettlement do
             xml['ram'].ApplicableTradeTax do
-              xml['ram'].TypeCode("VAT") # Type de taxe (VAT), toujours "VAT" en UE (BT-151)
-              xml['ram'].CategoryCode(item[:vat_category]) # Code catégorie TVA de la ligne (BT-151). Une valeur parmi : {'A', 'AA', 'AB', 'AC', 'AD', 'AE', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'O', 'S', 'Z'}
-              xml['ram'].RateApplicablePercent(item[:vat_rate]) # Taux de TVA appliqué (%) (BT-152)
+              xml['ram'].TypeCode("VAT") # VAT type (always "VAT" in the EU) (BT-151)
+              xml['ram'].CategoryCode(item[:vat_category]) # VAT category code for the line item (BT-151). One among these: {'A', 'AA', 'AB', 'AC', 'AD', 'AE', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'O', 'S', 'Z'}
+              xml['ram'].RateApplicablePercent(item[:vat_rate]) # VAT rate applied (%) (BT-152)
             end
             if item[:discount].present?
               discount = item[:discount]
               xml['ram'].SpecifiedTradeAllowanceCharge do
                 xml['ram'].ChargeIndicator do
-                  xml['udt'].Indicator("false") # true = charge (frais supplémentaires), false = allowance (réduction/remise)
+                  xml['udt'].Indicator("false") # true = charge (additional fees), false = allowance (discount/allowance)
                 end
-                xml['ram'].CalculationPercent(discount[:percentage]) if discount[:percentage].present? # Pourcentage de remise applicable à la ligne de facture (BT-138)
-                xml['ram'].ActualAmount(discount[:total_amount]) # Montant de la remise applicable à la ligne de facture (BT-136)
-                xml['ram'].Reason(discount[:reason]) if discount[:reason].present? # Motif de la remise applicable à la ligne de facture (BT-139)
-                xml['ram'].ReasonCode(discount[:reason_code]) if discount[:reason_code].present? # Code de motif de la remise applicable à la ligne de facture (BT-140)
-                # xml['ram'].BasisAmount(discount[:base]) # Assiette de la remise applicable à la ligne de facture (BT-137)
+                xml['ram'].CalculationPercent(discount[:percentage]) if discount[:percentage].present? # Discount percentage applicable to the invoice line (BT-138)
+                xml['ram'].ActualAmount(discount[:total_amount]) # Discount amount applicable to the invoice line (BT-136)
+                xml['ram'].Reason(discount[:reason]) if discount[:reason].present? # Reason for the discount on the invoice line (BT-139)
+                xml['ram'].ReasonCode(discount[:reason_code]) if discount[:reason_code].present? # Reason code for the discount on the invoice line (BT-140)
+                # xml['ram'].BasisAmount(discount[:base]) # Discount basis applicable to invoice line (BT-137)
               end
             end
             xml['ram'].SpecifiedTradeSettlementLineMonetarySummation do
-              xml['ram'].LineTotalAmount(item[:line_total]) # Montant net de la ligne HT = Quantité × Prix unitaire net (BT-131)
+              xml['ram'].LineTotalAmount(item[:line_total]) # Net line amount excluding VAT = Quantity × Net unit price (BT-131)
             end
           end
         end
@@ -260,23 +127,23 @@ module UnovaFacturX
 
       xml['ram'].ApplicableHeaderTradeDelivery do
         xml['ram'].ShipToTradeParty do
-          xml['ram'].GlobalID(delivery[:gln], schemeID: delivery[:gln_scheme]) if delivery[:gln].present? && delivery[:gln_scheme].present? # Identifiant global du lieu de livraison (BT-71) (optionnel) | schemeID -> 0088: GLN (GS1), 0002: SIRENE (France), 9906: SIRET, 9915: TVA intracom FR, 0060:	DUNS
+          xml['ram'].GlobalID(delivery[:gln], schemeID: delivery[:gln_scheme]) if delivery[:gln].present? && delivery[:gln_scheme].present? # Global identifier of the delivery location (BT-71)  | Scheme identifiers: 0088: GLN (GS1), 0002: SIRENE (France), 9906: SIRET, 9915: EU VAT number (FR), 0060: DUNS
 
           if delivery[:address].present?
             address = delivery[:address]
             xml['ram'].PostalTradeAddress do
-              xml['ram'].PostcodeCode(address[:postcode]) if address[:postcode].present? # Code postal
-              xml['ram'].LineOne(address[:line1]) if address[:line1].present? # Rue
-              xml['ram'].LineTwo(address[:line2]) if address[:line2].present? # Complément
-              xml['ram'].CityName(address[:city]) if address[:city].present? # Ville
-              xml['ram'].CountryID(address[:country]) if address[:country].present? # Code pays
+              xml['ram'].PostcodeCode(address[:postcode]) if address[:postcode].present? # Delivery postal code
+              xml['ram'].LineOne(address[:line1]) if address[:line1].present? # Street address
+              xml['ram'].LineTwo(address[:line2]) if address[:line2].present? # Address complement
+              xml['ram'].CityName(address[:city]) if address[:city].present? # City
+              xml['ram'].CountryID(address[:country]) if address[:country].present? # Country code
             end
           end
         end
         if delivery[:date].present?
           xml['ram'].ActualDeliverySupplyChainEvent do
             xml['ram'].OccurrenceDateTime do
-              xml['udt'].DateTimeString(delivery[:date], format: "102") # Date effective de livraison, format YYYYMMDD (BT-72)
+              xml['udt'].DateTimeString(delivery[:date], format: "102") # Actual delivery date in YYYYMMDD format (BT-72)
             end
           end
         end
@@ -287,45 +154,45 @@ module UnovaFacturX
       xml['ram'].ApplicableHeaderTradeAgreement do
         xml['ram'].SellerTradeParty do
           seller = @document[:seller]
-          xml['ram'].Name(seller[:name]) # Nom légal du vendeur (BT-27)
+          xml['ram'].Name(seller[:name]) # Seller legal name (BT-27)
           xml['ram'].SpecifiedLegalOrganization do
-            xml['ram'].ID(seller[:legal_id]) # Identifiant légal du vendeur (SIREN/SIRET ou équivalent) (BT-30)
+            xml['ram'].ID(seller[:legal_id]) # Seller legal identifier (SIREN/SIRET or equivalent) (BT-30)
           end
           xml['ram'].PostalTradeAddress do
             address = seller[:address]
-            xml['ram'].PostcodeCode(address[:postcode]) # Code postal
-            xml['ram'].LineOne(address[:line1]) # Rue
-            xml['ram'].LineTwo(address[:line2]) if address[:line2].present? # Complément
-            xml['ram'].CityName(address[:city]) # Ville
-            xml['ram'].CountryID(address[:country]) # Code pays
+            xml['ram'].PostcodeCode(address[:postcode]) # Postal code
+            xml['ram'].LineOne(address[:line1]) # Street address
+            xml['ram'].LineTwo(address[:line2]) if address[:line2].present? # Address complement
+            xml['ram'].CityName(address[:city]) # City
+            xml['ram'].CountryID(address[:country]) # Country code
           end
           if seller[:vat_number].present?
             xml['ram'].SpecifiedTaxRegistration do
-              xml['ram'].ID(seller[:vat_number], schemeID: "VA") # Numéro TVA vendeur (BT-31)
+              xml['ram'].ID(seller[:vat_number], schemeID: "VA") # Seller VAT number (BT-31)
             end
           end
         end
         xml['ram'].BuyerTradeParty do
           buyer = @document[:buyer]
-          xml['ram'].ID(buyer[:id]) # Identifiant du client (BT-46)
-          xml['ram'].Name(buyer[:name]) # Nom légal de l'entreprise cliente (BT-44)
+          xml['ram'].ID(buyer[:id]) # Buyer identifier (BT-46)
+          xml['ram'].Name(buyer[:name]) # Buyer legal name (BT-44)
           if buyer[:contact].present?
             contact = buyer[:contact]
             xml['ram'].DefinedTradeContact do
-              xml['ram'].PersonName(contact[:name]) # Nom du contact chez le client (BT-56) (optionnel)
+              xml['ram'].PersonName(contact[:name]) # Contact name for the buyer (BT-56) 
             end
           end
           xml['ram'].PostalTradeAddress do
             address = buyer[:address]
-            xml['ram'].PostcodeCode(address[:postcode]) # Code postal
-            xml['ram'].LineOne(address[:line1]) # Rue
-            xml['ram'].LineTwo(address[:line2]) if address[:line2].present? # Complément
-            xml['ram'].CityName(address[:city]) # Ville
-            xml['ram'].CountryID(address[:country]) # Code pays
+            xml['ram'].PostcodeCode(address[:postcode]) # Buyer postal code
+            xml['ram'].LineOne(address[:line1]) # Street address
+            xml['ram'].LineTwo(address[:line2]) if address[:line2].present? # Address complement
+            xml['ram'].CityName(address[:city]) # City
+            xml['ram'].CountryID(address[:country]) # Country code
           end
           if buyer[:vat_number].present?
             xml['ram'].SpecifiedTaxRegistration do
-              xml['ram'].ID(buyer[:vat_number], schemeID: "VA") # Numéro TVA vendeur (BT-48)
+              xml['ram'].ID(buyer[:vat_number], schemeID: "VA") # Buyer VAT number (BT-48)
             end
           end
         end
@@ -335,25 +202,25 @@ module UnovaFacturX
     def build_applicable_header_trade_settlement(xml)
       xml['ram'].ApplicableHeaderTradeSettlement do
         payment = @document[:payment_means]
-        # xml['ram'].PaymentReference("XXXX") # Référence de paiement (ex : référence virement) (BT-83)
-        xml['ram'].InvoiceCurrencyCode(@devise)
+        # xml['ram'].PaymentReference("XXXX") # Payment reference (e.g. bank transfer reference) (BT-83)
+        xml['ram'].InvoiceCurrencyCode(@currency) # Invoice currency code
         xml['ram'].SpecifiedTradeSettlementPaymentMeans do
-          xml['ram'].TypeCode(payment[:type_code]) # Code moyen de paiement UNCL 4461 (BT-81)
-          if %w[30 49].include?(payment[:type_code].to_s) && payment[:iban].present? # 30 : Virement, 49 : Prélèvement automatique
+          xml['ram'].TypeCode(payment[:type_code]) # Payment method code UNCL 4461 (BT-81)
+          if %w[30 49].include?(payment[:type_code].to_s) && payment[:iban].present? # 30: Bank transfer, 49: Direct debit
             xml['ram'].PayeePartyCreditorFinancialAccount do
-              xml['ram'].IBANID(payment[:iban]) # IBAN du compte bénéficiaire (BT-84)
+              xml['ram'].IBANID(payment[:iban]) # Payee IBAN (BT-84)
             end
           end
         end
         @document[:vat_breakdown].each do |vat|
           xml['ram'].ApplicableTradeTax do
-            xml['ram'].CalculatedAmount(vat[:tax_amount]) # Montant total de TVA pour le taux concerné (BT-117)
-            xml['ram'].TypeCode("VAT") # TVA
-            xml['ram'].ExemptionReason(vat[:exemption_reason]) if vat[:vat_category] == "E" && vat[:exemption_reason].present? # Motif d'exonération de la TVA (BT-120)
-            xml['ram'].ExemptionReasonCode(vat[:exemption_reason_code]) if vat[:vat_category] == "E" && vat[:exemption_reason_code].present? # Code de motif d'exonération de la TVA (BT-121)
-            xml['ram'].BasisAmount(vat[:taxable_amount]) # Base taxable HT pour le taux concerné (BT-116)
-            xml['ram'].CategoryCode(vat[:vat_category]) # Code catégorie TVA du breakdown (BT-118). Une valeur parmi : {'A', 'AA', 'AB', 'AC', 'AD', 'AE', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'O', 'S', 'Z'}
-            xml['ram'].RateApplicablePercent(vat[:vat_rate]) # Taux de TVA appliqué (%) (BT-119)
+            xml['ram'].CalculatedAmount(vat[:tax_amount]) # VAT calculated amount for the given rate (BT-117)
+            xml['ram'].TypeCode("VAT") # VAT type (always "VAT" in the EU)
+            xml['ram'].ExemptionReason(vat[:exemption_reason]) if vat[:vat_category] == "E" && vat[:exemption_reason].present? # VAT exemption reason (BT-120)
+            xml['ram'].ExemptionReasonCode(vat[:exemption_reason_code]) if vat[:vat_category] == "E" && vat[:exemption_reason_code].present? # VAT exemption reason code (BT-121)
+            xml['ram'].BasisAmount(vat[:taxable_amount]) # Taxable base amount for the VAT rate (BT-116)
+            xml['ram'].CategoryCode(vat[:vat_category]) # VAT category code (BT-118). One among these : {'A', 'AA', 'AB', 'AC', 'AD', 'AE', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'O', 'S', 'Z'}
+            xml['ram'].RateApplicablePercent(vat[:vat_rate]) # VAT rate applied (%) (BT-119)
           end
         end
 
@@ -361,19 +228,19 @@ module UnovaFacturX
           @document[:discount].each do |discount|
             xml['ram'].SpecifiedTradeAllowanceCharge do
               xml['ram'].ChargeIndicator do
-                xml['udt'].Indicator("false") # true = charge (frais supplémentaires), false = allowance (réduction/remise)
+                xml['udt'].Indicator("false") # true = charge (additional fees), false = allowance (discount/allowance)
               end
-              xml['ram'].CalculationPercent(discount[:percentage]) if discount[:percentage].present? # % de remise au niveau du document si la remise est en % (BT-94)
-              xml['ram'].ActualAmount(discount[:total_amount]) # Montant de la remise au niveau du document pour le taux TVA concerné (BT-92)
-              xml['ram'].Reason(discount[:reason]) if discount[:reason].present? # Motif de la remise au niveau du document (BT-97)
-              xml['ram'].ReasonCode(discount[:reason_code]) if discount[:reason_code].present? # Code de motif de la remise au niveau du document (BT-98)
-              # xml['ram'].BasisAmount(discount[:base]) # Base sur laquelle la remise est appliquée au niveau du document pour le taux TVA concerné (BT-93)
+              xml['ram'].CalculationPercent(discount[:percentage]) if discount[:percentage].present? # Discount percentage at document level (BT-94)
+              xml['ram'].ActualAmount(discount[:total_amount]) # Discount amount at document level for VAT rate (BT-92)
+              xml['ram'].Reason(discount[:reason]) if discount[:reason].present? # Reason for document-level discount (BT-97)
+              xml['ram'].ReasonCode(discount[:reason_code]) if discount[:reason_code].present? # Reason code for document-level discount (BT-98)
+              # xml['ram'].BasisAmount(discount[:base]) # Base amount used for discount calculation (BT-93)
               xml['ram'].CategoryTradeTax do
-                xml['ram'].TypeCode("VAT") # Code de type de TVA de la remise (BT-95)
-                xml['ram'].CategoryCode(discount[:vat_category]) # Code catégorie TVA (BT-118). Une valeur parmi : {'A', 'AA', 'AB', 'AC', 'AD', 'AE', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'O', 'S', 'Z'}
-                xml['ram'].RateApplicablePercent(discount[:vat_rate]) # Taux de TVA appliqué (%) (BT-119)
+                xml['ram'].TypeCode("VAT") # VAT type (always "VAT" in the EU) (BT-95)
+                xml['ram'].CategoryCode(discount[:vat_category]) # VAT category for discount (BT-118). One among these : {'A', 'AA', 'AB', 'AC', 'AD', 'AE', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'O', 'S', 'Z'}
+                xml['ram'].RateApplicablePercent(discount[:vat_rate]) # VAT rate applied to discount (BT-119)
               end
-              # xml['ram'].RateApplicablePercent("0.00") # Taux de TVA de la remise au niveau du document (BT-96)
+              # xml['ram'].RateApplicablePercent("0.00") # VAT rate for the document-level discount (BT-96)
             end
           end
         end
@@ -386,16 +253,16 @@ module UnovaFacturX
                 xml['udt'].DateTimeString(totals[:due_date], format: "102") # Payment due date (BT-9)
               end
             end
-            xml['ram'].Description(totals[:description]) if totals[:description].present? # Payment terms (BT-20)
+            xml['ram'].Description(totals[:description]) if totals[:description].present? # Payment terms description (BT-20)
           end
         end
         xml['ram'].SpecifiedTradeSettlementHeaderMonetarySummation do
-          xml['ram'].LineTotalAmount(totals[:line_total_ht]) # Total HT des lignes sans discounts (BT-106)
-          xml['ram'].AllowanceTotalAmount(totals[:total_discount]) if @document[:discount].present? && totals[:total_discount].present? # Somme des remises au niveau du document (BT-107)
-          xml['ram'].TaxBasisTotalAmount(totals[:tax_basis_total_ht]) # Total des bases taxables HT (avec discounts) (BT-109)
-          xml['ram'].TaxTotalAmount(totals[:tax_total], currencyID: @devise) # Montant total de TVA (BT-110)
-          xml['ram'].GrandTotalAmount(totals[:grand_total_ttc]) # Total TTC (BT-112)
-          xml['ram'].DuePayableAmount(totals[:amount_due]) if totals[:amount_due].present? # Montant restant dû (BT-115)
+          xml['ram'].LineTotalAmount(totals[:line_total_ht]) # Total line amount excluding VAT (BT-106)
+          xml['ram'].AllowanceTotalAmount(totals[:total_discount]) if @document[:discount].present? && totals[:total_discount].present? # Total document-level discounts (BT-107)
+          xml['ram'].TaxBasisTotalAmount(totals[:tax_basis_total_ht]) # Total taxable base amount (BT-109)
+          xml['ram'].TaxTotalAmount(totals[:tax_total], currencyID: @currency) # Total VAT amount (BT-110)
+          xml['ram'].GrandTotalAmount(totals[:grand_total_ttc]) # Total amount including VAT (BT-112)
+          xml['ram'].DuePayableAmount(totals[:amount_due]) if totals[:amount_due].present? # Amount remaining to be paid (BT-115)
         end
       end
     end
@@ -415,7 +282,7 @@ module UnovaFacturX
       )
       classpath = "#{jar_path}:#{resolver_path}"
 
-      # Écrit le XML dans un fichier temp
+      # Writes the XML to a temporary file.
       tmp_xml = Tempfile.new(['invoice', '.xml'])
       tmp_xml.write(doc.to_xml)
       tmp_xml.flush
@@ -429,7 +296,7 @@ module UnovaFacturX
       tmp_xml.close
       tmp_xml.unlink
 
-      raise "Java non disponible" unless status.exitstatus != 127
+      raise "Java not available" if status.exitstatus == 127
 
       report = ::Nokogiri::XML(stdout)
 
@@ -445,7 +312,7 @@ module UnovaFacturX
         e.at_xpath('svrl:text', svrl_namespace)&.text&.strip
       end
 
-      raise "EN16931 validation échouée :\n#{messages.join("\n")}"
+      raise "EN16931 validation failed:\n#{messages.join("\n")}"
     end
   end
 end

data/lib/unova_factur_x.rb

@@ -10,13 +10,13 @@ require_relative "unova_factur_x/factur_x_generator"
 module UnovaFacturX
   class Error < StandardError; end
 
-  def self.generate(pdf:, document_hash:, type: :invoice, with_validations: true, devise: "EUR")
+  def self.generate(pdf:, document_hash:, type: :invoice, with_validations: true, currency: "EUR")
     unless %i[invoice credit].include?(type)
       raise ArgumentError, "Type must be :invoice or :credit (default is :invoice)"
     end
 
     # Génération du XML à partir du hash en entré
-    xml = UnovaFacturX::XmlGenerator.new(document_hash, type: type, validate: with_validations, devise: devise).call
+    xml = UnovaFacturX::XmlGenerator.new(document_hash, type: type, validate: with_validations, currency: currency).call
 
     # Génération et retour du PDF FacturX à partir du PDF en entré et du XML généré
     UnovaFacturX::FacturXGenerator.new(pdf: pdf, xml: xml).call

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unova_factur_x
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Rodolphe Limousin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hexapdf
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.18'
-description: Prends en entré un PDF et un hash de ses données et retourne un PDF au
-  format Factur-X
+description: Takes a PDF and a data hash as input and returns a Factur-X-compliant
+  PDF
 email:
 - rodolphe.limousin@unova.fr
 executables: []
@@ -54,9 +54,9 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - LICENSES/MPL-2.0.txt
-- LOGICIELS_TIER.txt
 - README.md
 - Rakefile
+- THIRD-PARTY_COMPONENTS.txt
 - lib/unova_factur_x.rb
 - lib/unova_factur_x/factur_x_generator.rb
 - lib/unova_factur_x/java/Saxon-HE-12.4.jar
@@ -67,7 +67,7 @@ files:
 - sig/unova_factur_x.rbs
 homepage: https://github.com/unovafr/unova_factur_x
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   homepage_uri: https://github.com/unovafr/unova_factur_x
   source_code_uri: https://github.com/unovafr/unova_factur_x
@@ -89,5 +89,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Génération de factures/avoirs au format Factur-X
+summary: Generation of invoices/credit notes in Factur-X format
 test_files: []

data/LOGICIELS_TIER.txt

@@ -1,29 +0,0 @@
-AVIS ET INFORMATIONS SUR LES LOGICIELS TIERS
-
-Ce projet inclut des composants logiciels tiers.
-
-------------------------------------------------------------
-1. Saxon-HE (processeur XSLT et XQuery)
-------------------------------------------------------------
-
-Nom : Saxon-HE
-Version : 12.4
-Auteur : Saxonica Limited
-Site officiel : https://www.saxonica.com/
-
-Licence : Mozilla Public License 2.0 (MPL-2.0)
-
-Droits d’auteur :
-Copyright (c) Saxonica Limited
-
-Saxon-HE est inclus dans cette distribution sous forme de fichier JAR précompilé et reste soumis à sa licence d’origine.
-
-Le texte complet de la licence MPL-2.0 est disponible ici :
-https://www.mozilla.org/en-US/MPL/2.0/
-
-Une copie de la licence MPL-2.0 est incluse dans ce projet :
-LICENSES/MPL-2.0.txt
-
-------------------------------------------------------------
-FIN DES AVIS
-------------------------------------------------------------