Improve another error message to help users debugging encoding issues

mquinson · Jun 12, 2024 · afe6e13 · afe6e13
1 parent 9785c59
commit afe6e13
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 20 deletions.
diff --git a/NEWS b/NEWS
@@ -11,6 +11,7 @@ __   __/ _ \|___  |___ /
 General:
  * Try to not fail when writing UTF po files with old Perl versions
    (GitHub's #495) [Ineiev].
+ * Improve various error messages to help users debugging encoding issues.
 
 Documentation:
  * Fix the doc of TransTractor::read() now that the refname is mandatory

diff --git a/lib/Locale/Po4a/Pod.pm b/lib/Locale/Po4a/Pod.pm
@@ -86,16 +86,35 @@ sub command {
         $charset =~ s/^\s*(.*?)\s*$/$1/s;
 
         my $master_charset = $self->get_in_charset;
-        croak wrap_mod(
-            "po4a::pod",
-            dgettext(
-                "po4a",
-                "The file %s declares %s as encoding, but you provided %s as master charset. Please change either setting."
-            ),
-            $self->{DOCPOD}{refname},
-            $charset,
-            $master_charset,
-        ) if ( length( $master_charset // '' ) > 0 && uc($charset) ne uc($master_charset) );
+        if ( length( $master_charset // '' ) > 0 && uc($charset) ne uc($master_charset) ) {
+            if (   ( $charset eq 'UTF-8' || lc($charset) eq 'utf8' )
+                && ( $master_charset eq 'UTF-8' || lc($master_charset) eq 'utf8' ) )
+            {
+                croak wrap_mod(
+                    "po4a::pod",
+                    dgettext(
+                        "po4a",
+                        "The file %s declares %s as encoding, but you provided %s as master charset. ".
+                        "Please change either setting because they really are different encoding in Perl ".
+                        "(see https://perldoc.perl.org/Encode#UTF-8-vs.-utf8-vs.-UTF8). You probably mean UTF-8."
+                    ),
+                    $self->{DOCPOD}{refname},
+                    $charset,
+                    $master_charset,
+                );
+            } else {
+                croak wrap_mod(
+                    "po4a::pod",
+                    dgettext(
+                        "po4a",
+                        "The file %s declares %s as encoding, but you provided %s as master charset. Please change either setting."
+                    ),
+                    $self->{DOCPOD}{refname},
+                    $charset,
+                    $master_charset,
+                );
+            }
+        }
 
         # The =encoding line will be added by docheader
     } else {

diff --git a/lib/Locale/Po4a/Xml.pm b/lib/Locale/Po4a/Xml.pm
@@ -899,16 +899,31 @@ sub tag_trans_xmlhead {
     my $out_charset = $self->get_out_charset;
 
     if ( defined $in_charset ) {
-        croak wrap_mod(
-            "po4a::xml",
-            dgettext(
-                "po4a",
-                "The file %s declares %s as encoding, but you provided %s as master charset. Please change either setting."
-            ),
-            $self->{'current_file'},
-            $in_charset,
-            $input_charset
-        ) if ( length( $input_charset // '' ) > 0 && uc($input_charset) ne uc($in_charset) );
+        if ( length( $input_charset // '' ) > 0 && uc($in_charset) ne uc($input_charset) ) {
+            if ($in_charset eq 'UTF-8' || lc($in_charset) eq 'utf8') && ($input_charset eq 'UTF-8' || lc($input_charset) eq 'utf8') {
+                croak wrap_mod(
+                    "po4a::pod",
+                    dgettext(
+                        "po4a",
+                        "The file %s declares %s as encoding, but you provided %s as master charset. Please change either setting because they really are different encoding in Perl. See https://perldoc.perl.org/Encode#UTF-8-vs.-utf8-vs.-UTF8"
+                    ),
+                    $self->{DOCPOD}{refname},
+                    $in_charset,
+                    $input_charset,
+                );
+            } else {
+                croak wrap_mod(
+                    "po4a::pod",
+                    dgettext(
+                        "po4a",
+                        "The file %s declares %s as encoding, but you provided %s as master charset. Please change either setting."
+                    ),
+                    $self->{DOCPOD}{refname},
+                    $in_charset,
+                    $input_charset,
+                );
+            }
+        }
 
         $tag =~ s/$in_charset/$out_charset/;
     } else {