Prepare to not localize private function descriptions

The overwhelming majority of localizable messages comes from
completions:

	$ ls share/completions/ | wc -l
	$ 1048

OTOH functions also contribute a small amount, mostly via their
descriptions (so usually just one per file).

	$ ls share/functions/ | wc -l
	$ 237

Most of these are private and almost never shown to the user, so it's
not worth bothering translators with them. So:

- Skip private (see the parent commit) and deprecated functions.
- Skip wrapper functions like grep (where the translation seems to
  be provided by apropos), and even the English description is not
  helpful.
  - Assume that most real systems have "seq", "realpath" etc.,
    so it's no use providing our own translations for our fallbacks.
- Mark fish's own functions as tier1, and some barely-used functiosn
  and completions as tier3, so we can order them that way in
  po/*.po. Most translators should only look at tier1 and tier2.
  In future we could disable localization for tier3.

See the explanation at the bottom of
tests/checks/message-localization-tier-is-declared.fish

Part of #11833

share/completions/!.fish

@@ -1 +1,2 @@
+# localization: tier1
 complete ! --wraps not

share/completions/[.fish

@@ -1 +1,2 @@
+# localization: tier1
 complete [ --wraps test

share/completions/fish_opt.fish

@@ -1,3 +1,5 @@
+# localization: skip(barely-used)
+
 set --local CONDITION '! __fish_seen_argument --short r --long required-val --short o --long optional-val'
 
 complete --command fish_opt --no-files

share/functions/N_.fish

@@ -1,3 +1,4 @@
-function N_ --description No-op
+# localization: skip(deprecated)
+function N_
     printf "%s" $argv
 end

share/functions/__fish_anyeditor.fish

@@ -1,4 +1,5 @@
-function __fish_anyeditor --description "Print a editor to use, or an error message"
+# localization: tier1
+function __fish_anyeditor
     set -l editor
     if set -q VISUAL
         echo $VISUAL | read -at editor

share/functions/__fish_cmd__complete_args.fish

@@ -1,4 +1,5 @@
-function __fish_cmd__complete_args -d 'Function to generate args'
+# localization: tier3
+function __fish_cmd__complete_args
     set -l current_token (commandline -tc)
 
     switch $current_token

share/functions/__fish_complete_bittorrent.fish

@@ -1,5 +1,6 @@
+# localization: tier3
+#
 # Bittorrent commands
-
 function __fish_complete_bittorrent
     complete -c $argv -l max_uploads -x --description "Maximum uploads at once"
     complete -c $argv -l keepalive_interval -x --description "Number of seconds between keepalives"

share/functions/__fish_complete_docutils.fish

@@ -1,4 +1,5 @@
-function __fish_complete_docutils -d "Completions for Docutils common options" -a cmd
+# localization: tier3
+function __fish_complete_docutils -a cmd
     complete -x -c $cmd -k -a "(__fish_complete_suffix .rst .txt)"
 
     # General Docutils Options

share/functions/__fish_complete_ftp.fish

@@ -1,4 +1,5 @@
-function __fish_complete_ftp -d 'Complete ftp, pftp' --argument-names ftp
+# localization: tier3
+function __fish_complete_ftp --argument-names ftp
     # Common across all ftp implementations
     complete -c $ftp -xa "(__fish_print_hostnames)" -d Hostname
     complete -c $ftp -s 4 -d 'Use IPv4 only'

share/functions/__fish_complete_gpg.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 #
 # Completions for the gpg program.
 #
@@ -15,7 +16,7 @@
 # removed. The remaining list of completions is still quite
 # impressive.
 
-function __fish_complete_gpg -d "Internal function for gpg completion code deduplication" -a __fish_complete_gpg_command
+function __fish_complete_gpg -a __fish_complete_gpg_command
     if string match -q 'gpg (GnuPG) 1.*' ($__fish_complete_gpg_command --version 2>/dev/null)
         complete -c $__fish_complete_gpg_command -l simple-sk-checksum -d 'Integrity protect secret keys by using a SHA-1 checksum'
         complete -c $__fish_complete_gpg_command -l no-sig-create-check -d "Do not verify each signature right after creation"

share/functions/__fish_complete_lpr.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __fish_complete_lpr -d 'Complete lpr common options' --argument-names cmd
     complete -c $cmd -s E -d 'Forces encryption when connecting to the server'
     complete -c $cmd -s U -d 'Specifies an alternate username' -xa '(__fish_complete_users)'

share/functions/__fish_complete_magick.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __fish_complete_magick
     complete -c $argv -o adjoin -d 'Join images into a single multi-image file'
     complete -c $argv -o affine -d 'Affine transform matrix [matrix]'

share/functions/__fish_complete_mount_opts.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __fish_print_user_ids
     if command -sq getent
         for line in (getent passwd)

share/functions/__fish_complete_mysql.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __fish_mysql_query -a query
     argparse -u 'u/user=' 'P/port=' 'h/host=' 'p/password=?' 'S/socket=' -- (commandline -px)
     set -l mysql_cmd mysql

share/functions/__fish_complete_netcat.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __fish_complete_netcat
     set -l nc $argv[1]
     set -l flavor $argv[-1]

share/functions/__fish_complete_pgrep.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __fish_complete_pgrep -d 'Complete pgrep/pkill' --argument-names cmd
     complete -c $cmd -xa '(__fish_complete_proc)'
     complete -c $cmd -s f -d 'Match pattern against full command line'

share/functions/__fish_complete_ssh.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __fish_complete_ssh -d "common completions for ssh commands" --argument-names command
     complete -c $command -s 4 -d "IPv4 only"
     complete -c $command -s 6 -d "IPv6 only"

share/functions/__fish_complete_wireshark.fish

@@ -1,3 +1,5 @@
+# localization: tier3
+#
 # Helper functions for wireshark/tshark/dumpcap completion
 
 function __fish_wireshark_choices

share/functions/__fish_complete_zfs_mountpoint_properties.fish

@@ -1,4 +1,5 @@
-function __fish_complete_zfs_mountpoint_properties -d "Completes with ZFS mountpoint properties"
+# localization: tier3
+function __fish_complete_zfs_mountpoint_properties
     set -l OS ""
     switch (uname)
         case Linux

share/functions/__fish_complete_zfs_ro_properties.fish

@@ -1,4 +1,5 @@
-function __fish_complete_zfs_ro_properties -d "Completes with ZFS read-only properties"
+# localization: tier3
+function __fish_complete_zfs_ro_properties
     echo -e "available\tAvailable space"
     echo -e "avail\tAvailable space"
     echo -e "compressratio\tAchieved compression ratio"

share/functions/__fish_complete_zfs_rw_properties.fish

@@ -1,4 +1,5 @@
-function __fish_complete_zfs_rw_properties -d "Completes with ZFS read-write properties"
+# localization: tier3
+function __fish_complete_zfs_rw_properties
     set -l OS ""
     switch (uname)
         case Linux

share/functions/__fish_complete_zfs_write_once_properties.fish

@@ -1,4 +1,5 @@
-function __fish_complete_zfs_write_once_properties -d "Completes with ZFS properties which can only be written at filesystem creation, and only be read thereafter"
+# localization: tier3
+function __fish_complete_zfs_write_once_properties
     set -l OS ""
     switch (uname)
         case Linux

share/functions/__fish_edit_command_if_at_cursor.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function __fish_edit_command_if_at_cursor --description 'If cursor is at the command token, edit the command source file'
     set -l tokens (commandline -xpc)
     set -l command

share/functions/__fish_git_prompt.fish

@@ -1,3 +1,4 @@
+# localization: skip(deprecated)
 function __fish_git_prompt
     # TODO: This name is deprecated, figure out a way to tell users.
     fish_git_prompt $argv

share/functions/__fish_hg_prompt.fish

@@ -1,3 +1,4 @@
+# localization: skip(deprecated)
 function __fish_hg_prompt
     fish_hg_prompt
 end

share/functions/__fish_list_current_token.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 # This function is typically bound to Alt-L, it is used to list the contents
 # of the directory under the cursor.
 

share/functions/__fish_pwd.fish

@@ -1,3 +1,4 @@
+# localization: skip(deprecated)
 function __fish_pwd --description "Show current path"
     if status test-feature regex-easyesc
         string replace -r '^/cygdrive/(.)?' '\U$1:' -- $PWD

share/functions/__fish_svn_prompt.fish

@@ -1,3 +1,4 @@
+# localization: skip(deprecated)
 function __fish_svn_prompt
     fish_svn_prompt
 end

share/functions/__fish_toggle_comment_commandline.fish

@@ -1,3 +1,5 @@
+# localization: tier1
+#
 # This is meant to be bound to key sequences such as \e#. It provides a simple way to quickly
 # comment/uncomment the current command. This is something introduced by the Korn shell (ksh) in
 # 1993. It allows you to capture a command in the shell history without executing it. Then

share/functions/__fish_vcs_prompt.fish

@@ -1,3 +1,4 @@
-function __fish_vcs_prompt --description "Print the prompts for all available vcsen"
+# localization: skip(deprecated)
+function __fish_vcs_prompt
     fish_vcs_prompt
 end

share/functions/__fish_whatis_current_token.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 # This function is typically bound to Alt-W, it is used to list man page entries
 # for the command under the cursor.
 function __fish_whatis_current_token -d "Show man page entries or function description related to the token under the cursor"

share/functions/__ssh_history_completions.fish

@@ -1,3 +1,4 @@
+# localization: tier3
 function __ssh_history_completions -d "Retrieve `user@host` entries from history"
     history --prefix ssh --max=100 | string replace -rf '.* ([A-Za-z0-9._:-]+@[A-Za-z0-9._:-]+).*' '$1'
 end

share/functions/_validate_int.fish

@@ -1,3 +1,5 @@
+# localization: tier1
+#
 # This function is intended to be used as a validation command for individual option specifications
 # given to the `argparse` command. It checks that the argument is a valid integer and optionally
 # whether it is in a reasonable range.

share/functions/abbr.fish

@@ -1,3 +1,5 @@
+# localization: skip(deprecated)
+#
 # This file intentionally left blank.
 # This is provided to overwrite existing abbr.fish files, so that any abbr
 # function retained from past fish releases does not override the abbr builtin.

share/functions/alias.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function alias --description 'Creates a function wrapping a command'
     set -l options h/help s/save
     argparse -n alias --max-args=2 $options -- $argv

share/functions/cd.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # Wrap the builtin cd command to maintain directory history.
 #

share/functions/cdh.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 # Provide a menu of the directories recently navigated to and ask the user to
 # choose one to make the new current working directory (cwd).
 

share/functions/contains_seq.fish

@@ -1,3 +1,4 @@
+# localization: skip(barely-used)
 function contains_seq --description 'Return true if array contains a sequence'
     set -l printnext
     switch $argv[1]

share/functions/diff.fish

@@ -1,3 +1,4 @@
+# localization: skip(uses-apropos)
 # Use colours in diff output, if supported
 if command -vq diff; and command diff --color=auto /dev/null{,} >/dev/null 2>&1
     function diff

share/functions/dirh.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function dirh --description "Print the current directory history (the prev and next lists)"
     set -l options h/help
     argparse -n dirh --max-args=0 $options -- $argv

share/functions/dirs.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function dirs --description 'Print directory stack'
     set -l options h/help c
     argparse -n dirs --max-args=0 $options -- $argv

share/functions/down-or-search.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function down-or-search -d "search forward or move down 1 line"
     # If we are already in search mode, continue
     if commandline --search-mode

share/functions/edit_command_buffer.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function edit_command_buffer --description 'Edit the command buffer in an external editor'
     set -l tmpdir (__fish_mktemp_relative -d fish)
     or return 1

share/functions/export.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function export --description 'Set env variable. Alias for `set -gx` for bash compatibility.'
     if not set -q argv[1]
         set -x

share/functions/fish_opt.fish

@@ -1,3 +1,5 @@
+# localization: skip(barely-used)
+
 # This is a helper function for `fish_opt`. It does some basic validation of the arguments.
 function __fish_opt_validate_args --no-scope-shadowing
     if not set -q _flag_validate && test (count $argv) -ne 0

share/functions/funced.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function funced --description 'Edit function definition'
     set -l options h/help 'e/editor=' i/interactive s/save
     argparse -n funced --max-args=1 $options -- $argv

share/functions/funcsave.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function funcsave --description "Save the current definition of all specified functions to file"
     set -l options q/quiet h/help d/directory=
     argparse -n funcsave $options -- $argv

share/functions/grep.fish

@@ -1,3 +1,4 @@
+# localization: skip(uses-apropos)
 #
 # Match colors for grep, if supported
 #

share/functions/help.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function help --description 'Show help for the fish shell'
     set -l options h/help
     argparse -n help $options -- $argv

share/functions/history.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # Wrap the builtin history command to provide additional functionality.
 #

share/functions/isatty.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function isatty -d "Tests if a file descriptor is a tty"
     set -l options h/help
     argparse -n isatty $options -- $argv

share/functions/la.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # These are very common and useful
 #

share/functions/ll.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # These are very common and useful
 #

share/functions/ls.fish

@@ -1,4 +1,5 @@
-function ls --description "List contents of directory"
+# localization: skip(uses-apropos)
+function ls
     # Make ls use colors and show indicators if we are on a system that supports that feature and writing to stdout.
     #
 

share/functions/man.fish

@@ -1,9 +1,11 @@
+# localization: skip(uses-apropos)
+
 if not command -qs man
     # see #5329 and discussion at https://github.com/fish-shell/fish-shell/commit/13e025bdb01cc4dd08463ec497a0a3495873702f
     exit
 end
 
-function man --description "Format and display the on-line manual pages"
+function man
     # Work around the "builtin" manpage that everything symlinks to,
     # by prepending our fish datadir to man. This also ensures that man gives fish's
     # man pages priority, without having to put fish's bin directories first in $PATH.

share/functions/nextd-or-forward-token.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function nextd-or-forward-token --description "If commandline is empty, run nextd; else move one argument to the right"
     if test "$(commandline; printf .)" = \n.
         nextd

share/functions/nextd.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function nextd --description "Move forward in the directory history"
     set -l options h/help l/list
     argparse -n nextd --max-args=1 $options -- $argv

share/functions/open.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # This allows us to use 'open FILENAME' to open a given file in the default
 # application for the file.

share/functions/popd.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function popd --description "Pop directory from the stack and cd to it"
     if count $argv >/dev/null
         switch $argv[1]

share/functions/prevd-or-backward-token.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function prevd-or-backward-token --description "If commandline is empty, run prevd; else move one argument to the left"
     if test "$(commandline; printf .)" = \n.
         prevd

share/functions/prevd.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function prevd --description "Move back in the directory history"
     set -l options h/help l/list
     argparse -n prevd --max-args=1 $options -- $argv

share/functions/prompt_hostname.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function prompt_hostname --description 'short hostname for the prompt'
     string replace -r -- "\..*" "" $hostname
 end

share/functions/prompt_login.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function prompt_login --description "display user name for the prompt"
     if not set -q __fish_machine
         set -g __fish_machine

share/functions/prompt_pwd.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function prompt_pwd --description 'short CWD for the prompt'
     set -l options h/help d/dir-length= D/full-length-dirs=
     argparse -n prompt_pwd $options -- $argv

share/functions/psub.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function psub --description "Read from stdin into a file and output the filename. Remove the file when the command that called psub exits."
     set -l options -x 'f,F' h/help f/file F/fifo 's/suffix=' T-testing
     argparse -n psub --max-args=0 $options -- $argv

share/functions/pushd.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 function pushd --description 'Push directory to stack'
     set -l rot_r
     set -l rot_l

share/functions/realpath.fish

@@ -1,3 +1,5 @@
+# localization: skip(uses-apropos)
+
 # Provide a minimalist realpath implementation to help deal with platforms that may not provide it
 # as a command. If an external realpath or grealpath command is available simply pass all arguments
 # thru to it. If not fallback to our builtin.
@@ -7,7 +9,7 @@
 # However, we only want our builtin if there is no external realpath command.
 
 if command -sq realpath
-    function realpath -d "print the resolved path [command realpath]"
+    function realpath
         command realpath $argv
     end
     exit 0
@@ -15,7 +17,7 @@ end
 
 # If there is a HomeBrew installed version of GNU realpath named grealpath use that.
 if command -sq grealpath
-    function realpath -d "print the resolved path [command grealpath]"
+    function realpath
         command grealpath $argv
     end
     exit 0
@@ -42,14 +44,14 @@ function realpath -d "return an absolute path without symlinks"
     # We don't implement any of the other flags so if any are set it's an error.
     if string match -q '_flag_*' -- (set -l)
         set -l flags (set -l | string replace --filter --regex '_flag_\w+\s*' '' | sort -u)
-        printf (_ "%s: These flags are not allowed by fish realpath: '%s'") realpath "$flags" >&2
+        printf "realpath: These flags are not allowed by fish realpath: '%s'" "$flags" >&2
         echo >&2
         __fish_print_help realpath
         return 1
     end
 
     if not set -q argv[1]
-        printf (_ "%ls: Expected at least %d args, got only %d\n") realpath 1 0 >&2
+        printf "realpath: Expected at least %d args, got only %d\n" 1 0 >&2
         return 1
     end
 

share/functions/seq.fish

@@ -1,3 +1,5 @@
+# localization: skip(uses-apropos)
+
 # If seq is not installed, then define a function that invokes __fish_fallback_seq
 # We can't call type here because that also calls seq
 
@@ -7,18 +9,18 @@ end
 
 if command -sq gseq
     # No seq provided by the OS, but GNU coreutils was apparently installed, fantastic
-    function seq --description "Print sequences of numbers (gseq)"
+    function seq
         gseq $argv
     end
     exit
 end
 
 # No seq command
-function seq --description "Print sequences of numbers"
+function seq
     __fish_fallback_seq $argv
 end
 
-function __fish_fallback_seq --description "Fallback implementation of the seq command"
+function __fish_fallback_seq
     set -l from 1
     set -l step 1
     set -l to 1
@@ -39,13 +41,13 @@ function __fish_fallback_seq --description "Fallback implementation of the seq c
             set step $argv[2]
             set to $argv[3]
         case '*'
-            printf (_ "%s: Expected 1, 2 or 3 arguments, got %d\n") seq (count $argv) >&2
+            printf "seq: Expected 1, 2 or 3 arguments, got %d\n" (count $argv) >&2
             return 1
     end
 
     for i in $from $step $to
         if not string match -rq -- '^-?[0-9]*([0-9]*|\.[0-9]+)$' $i
-            printf (_ "%s: '%s' is not a number\n") seq $i >&2
+            printf "seq: '%s' is not a number\n" $i >&2
             return 1
         end
     end

share/functions/setenv.fish

@@ -1,4 +1,5 @@
-function setenv --description 'Set an env var for csh compatibility.'
+# localization: tier1
+function setenv
     # No arguments should cause the current env vars to be displayed.
     if not set -q argv[1]
         env
@@ -27,7 +28,7 @@ function setenv --description 'Set an env var for csh compatibility.'
         # This message is verbatim from csh. We don't really need to do this but if we don't fish
         # will display a different error message which might confuse someone expecting the csh
         # message.
-        printf (_ '%s: Variable name must contain alphanumeric characters\n') setenv >&2
+        echo "setenv: Variable name must contain alphanumeric characters" >&2
         return 1
     end
 

share/functions/suspend.fish

@@ -1,3 +1,5 @@
+# localization: tier1
+
 function suspend --description 'Suspend the current shell.'
     set -l options h/help f/force
     argparse -n suspend --max-args=1 $options -- $argv

share/functions/trap.fish

@@ -1,3 +1,5 @@
+# localization: tier1
+
 # This defines a compatibility shim for the `trap` command found in other shells like bash and zsh.
 function trap -d 'Perform an action when the shell receives a signal'
     set -l options h/help l/list-signals p/print

share/functions/umask.fish

@@ -1,3 +1,5 @@
+# localization: tier1
+
 # Support the usual (i.e., bash compatible) `umask` UI. This reports or modifies the magic global
 # `umask` variable which is monitored by the fish process.
 

share/functions/up-or-search.fish

@@ -1,3 +1,4 @@
+# localization: tier1
 # Depending on cursor position and current mode, either search backward or move up one line"
 function up-or-search -d "Search back or move cursor up 1 line"
     # If we are already in search mode, continue

share/functions/vared.fish

@@ -1,4 +1,5 @@
-#
+# localization: tier1
+
 # This is a neat function, stolen from zsh. It allows you to edit the
 # value of a variable interactively.
 #

tests/checks/functions.fish

@@ -41,7 +41,7 @@ set x (functions -v -D vared)
 if test (count $x) -ne 5
     or not string match -rq '.*functions/vared\.fish' $x[1]
     or test $x[2] != autoloaded
-    or test $x[3] != 6
+    or test $x[3] != 7
     or test $x[4] != scope-shadowing
     or test $x[5] != 'Edit variable value'
     echo "Unexpected output for 'functions -v -D vared': $x" >&2

tests/checks/message-localization-tier-is-declared.fish

@@ -0,0 +1,80 @@
+# RUN: fish=%fish %fish %s
+#REQUIRES: command -v msgfmt
+#REQUIRES: %fish -c 'status buildinfo | grep localize-messages'
+
+set -l workspace_root (path resolve -- (status dirname)/../../)
+
+set -g ok true
+
+for file in $workspace_root/share/functions/*.fish
+    function error --inherit-variable workspace_root --inherit-variable file
+        echo "$(string replace $workspace_root/ '' $file):1: error: $argv"
+        set -g ok false
+    end
+    set -l basename (path basename $file)
+    set -l tier
+    set -l localize_directives (string match -r '^# localization:.*' <$file)
+    if test (count $localize_directives) -gt 1
+        error 'multiple '# localization:' directives'
+        continue
+    end
+    if set -q localize_directives[1]
+        if not set tier (string replace -rf -- \
+                '^# localization: (tier[123]|skip(?:\(\S*\))?)$' '$1' \
+                $localize_directives)
+            error 'invalid '# localization:' directive'
+            continue
+        end
+    end
+    if string match -q -- 'fish_*' $basename
+        if set -q tier[1] && test $tier != 'skip(barely-used)'
+            error "unexpected '# localization:' directive in fish_* file, those are currently implicitly tier1"
+        end
+        continue
+    end
+    if not set -q tier[1]
+        error "missing '^# localization: (tier[123]|skip)\$' directive"
+        continue
+    end
+end
+
+if $ok
+    return
+end
+
+# If the test fails, output some flight rules. Here's some rationale:
+#
+# Files named 'share/functions/fish_*' are implicitly tier1 unless overridden.
+#
+# Private functions (starting with __fish) are probably not worth bothering translators.
+# The only thing that's translated is usually the function description.
+# Most of those private functions will barely ever be seen by most users.
+# They are shown when:
+#   - typing '__fish_' TAB, but only if the function has been loaded before.
+#   - running 'type __fish_ps' or 'functions __fish_ps'.
+# The exception is if a function is directly or indirectly called by a default
+# binding; then the user might look it up with 'type __fish_list_current_token'.
+# So we use tier1 (for interesting ones) until these are un-dundered and properly documented.
+#
+# Beyond functions, completions for share/completions/<name>.fish are implicitly 'tier3',
+# unless doc_src/cmds/<name>.rst exists, in which case they are 'tier1'.  This can be overridden.
+# For common tools like coreutils, use 'tier2'.
+#
+# Wrapper functions like grep don't need translations because we use 'apropos grep'.
+
+echo "
+- Use '# localization: tier1' for
+  - user-visible functions provided by fish such as 'll'
+  - functions used in bindings like '__fish_list_current_token'
+- Use '# localization: tier2' for:
+  - rarely-used or less important functions provided by fish.
+  - completions for common tools like coreutils
+- Use '# localization: tier3'
+  - for completions that add for third-party commands, or functions that do the same
+    E.g. the ones that contain 'complete foo ... -d some-translatable-string'.
+- Use '# localization: skip(<reason>)' in function files that should not be translated.
+  - 'skip(private)' for private functions, unless they are used in bindings
+  - 'skip(uses-apropos)' for wrapper functions
+  - 'skip(deprecated)' for functions that have been superseded
+  - 'skip(barely-used)' for functions that are not documented or probably barely used
+"

tests/checks/type.fish

@@ -38,7 +38,7 @@ type sh
 type realpath | grep -v "^  *"
 # CHECK: realpath is a function with definition
 # CHECK: # Defined in {{.*}}functions/realpath.fish @ line {{\d+}}
-# CHECK: function realpath --description {{.+}}
+# CHECK: function realpath
 # CHECK: end
 
 type -t realpath foobar