Prepare to not localize private function descriptions

krobelus · krobelus · commit d835c5252acb · 2025-09-30T11:47:26.000+02:00
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 fish-shell#11833
diff --git a/share/completions/!.fish b/share/completions/!.fish
@@ -1 +1,2 @@
+# localization: tier1
 complete ! --wraps not
diff --git a/share/completions/[.fish b/share/completions/[.fish
@@ -1 +1,2 @@
+# localization: tier1
 complete [ --wraps test
diff --git a/share/completions/fish_opt.fish b/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
diff --git a/share/functions/N_.fish b/share/functions/N_.fish
@@ -1,3 +1,4 @@
-function N_ --description No-op
+# localization: skip(deprecated)
+function N_
     printf "%s" $argv
 end
diff --git a/share/functions/__fish_anyeditor.fish b/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
diff --git a/share/functions/__fish_cmd__complete_args.fish b/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
diff --git a/share/functions/__fish_complete_bittorrent.fish b/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"
diff --git a/share/functions/__fish_complete_docutils.fish b/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
diff --git a/share/functions/__fish_complete_ftp.fish b/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'
diff --git a/share/functions/__fish_complete_gpg.fish b/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"
diff --git a/share/functions/__fish_complete_lpr.fish b/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)'
diff --git a/share/functions/__fish_complete_magick.fish b/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]'
diff --git a/share/functions/__fish_complete_mount_opts.fish b/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)
diff --git a/share/functions/__fish_complete_mysql.fish b/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
diff --git a/share/functions/__fish_complete_netcat.fish b/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]
diff --git a/share/functions/__fish_complete_pgrep.fish b/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'
diff --git a/share/functions/__fish_complete_ssh.fish b/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"
diff --git a/share/functions/__fish_complete_wireshark.fish b/share/functions/__fish_complete_wireshark.fish
@@ -1,3 +1,5 @@
+# localization: tier3
+#
 # Helper functions for wireshark/tshark/dumpcap completion
 
 function __fish_wireshark_choices
diff --git a/share/functions/__fish_complete_zfs_mountpoint_properties.fish b/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
diff --git a/share/functions/__fish_complete_zfs_ro_properties.fish b/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"
diff --git a/share/functions/__fish_complete_zfs_rw_properties.fish b/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
diff --git a/share/functions/__fish_complete_zfs_write_once_properties.fish b/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
diff --git a/share/functions/__fish_edit_command_if_at_cursor.fish b/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
diff --git a/share/functions/__fish_git_prompt.fish b/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
diff --git a/share/functions/__fish_hg_prompt.fish b/share/functions/__fish_hg_prompt.fish
@@ -1,3 +1,4 @@
+# localization: skip(deprecated)
 function __fish_hg_prompt
     fish_hg_prompt
 end
diff --git a/share/functions/__fish_list_current_token.fish b/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.
 
diff --git a/share/functions/__fish_pwd.fish b/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
diff --git a/share/functions/__fish_svn_prompt.fish b/share/functions/__fish_svn_prompt.fish
@@ -1,3 +1,4 @@
+# localization: skip(deprecated)
 function __fish_svn_prompt
     fish_svn_prompt
 end
diff --git a/share/functions/__fish_toggle_comment_commandline.fish b/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
diff --git a/share/functions/__fish_vcs_prompt.fish b/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
diff --git a/share/functions/__fish_whatis_current_token.fish b/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"
diff --git a/share/functions/__ssh_history_completions.fish b/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
diff --git a/share/functions/_validate_int.fish b/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.
diff --git a/share/functions/abbr.fish b/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.
diff --git a/share/functions/alias.fish b/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
diff --git a/share/functions/cd.fish b/share/functions/cd.fish
@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # Wrap the builtin cd command to maintain directory history.
 #
diff --git a/share/functions/cdh.fish b/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).
 
diff --git a/share/functions/contains_seq.fish b/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]
diff --git a/share/functions/diff.fish b/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
diff --git a/share/functions/dirh.fish b/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
diff --git a/share/functions/dirs.fish b/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
diff --git a/share/functions/down-or-search.fish b/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
diff --git a/share/functions/edit_command_buffer.fish b/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
diff --git a/share/functions/export.fish b/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
diff --git a/share/functions/fish_opt.fish b/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
diff --git a/share/functions/funced.fish b/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
diff --git a/share/functions/funcsave.fish b/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
diff --git a/share/functions/grep.fish b/share/functions/grep.fish
@@ -1,3 +1,4 @@
+# localization: skip(uses-apropos)
 #
 # Match colors for grep, if supported
 #
diff --git a/share/functions/help.fish b/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
diff --git a/share/functions/history.fish b/share/functions/history.fish
@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # Wrap the builtin history command to provide additional functionality.
 #
diff --git a/share/functions/isatty.fish b/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
diff --git a/share/functions/la.fish b/share/functions/la.fish
@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # These are very common and useful
 #
diff --git a/share/functions/ll.fish b/share/functions/ll.fish
@@ -1,3 +1,4 @@
+# localization: tier1
 #
 # These are very common and useful
 #
diff --git a/share/functions/ls.fish b/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.
     #
 
diff --git a/share/functions/man.fish b/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.
diff --git a/share/functions/nextd-or-forward-token.fish b/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
diff --git a/share/functions/nextd.fish b/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
diff --git a/share/functions/open.fish b/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.
diff --git a/share/functions/popd.fish b/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]
diff --git a/share/functions/prevd-or-backward-token.fish b/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
diff --git a/share/functions/prevd.fish b/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
diff --git a/share/functions/prompt_hostname.fish b/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
diff --git a/share/functions/prompt_login.fish b/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
diff --git a/share/functions/prompt_pwd.fish b/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
diff --git a/share/functions/psub.fish b/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
diff --git a/share/functions/pushd.fish b/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
diff --git a/share/functions/realpath.fish b/share/functions/realpath.fish
diff --git a/share/functions/seq.fish b/share/functions/seq.fish
diff --git a/share/functions/setenv.fish b/share/functions/setenv.fish
diff --git a/share/functions/suspend.fish b/share/functions/suspend.fish
diff --git a/share/functions/trap.fish b/share/functions/trap.fish
diff --git a/share/functions/umask.fish b/share/functions/umask.fish
diff --git a/share/functions/up-or-search.fish b/share/functions/up-or-search.fish
diff --git a/share/functions/vared.fish b/share/functions/vared.fish
diff --git a/tests/checks/functions.fish b/tests/checks/functions.fish
diff --git a/tests/checks/message-localization-tier-is-declared.fish b/tests/checks/message-localization-tier-is-declared.fish
diff --git a/tests/checks/type.fish b/tests/checks/type.fish

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
	`1`	`+# localization: tier1`
`1`	`2`	`complete ! --wraps not`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
	`1`	`+# localization: tier1`
`1`	`2`	`complete [ --wraps test`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# localization: skip(barely-used)`
	`2`	`+`
`1`	`3`	`set --local CONDITION '! __fish_seen_argument --short r --long required-val --short o --long optional-val'`
`2`	`4`
`3`	`5`	`complete --command fish_opt --no-files`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+# localization: tier3`
`1`	`2`	`#`
`2`	`3`	`# Completions for the gpg program.`
`3`	`4`	`#`
`@@ -15,7 +16,7 @@`
`15`	`16`	`# removed. The remaining list of completions is still quite`
`16`	`17`	`# impressive.`
`17`	`18`
`18`		`-function __fish_complete_gpg -d "Internal function for gpg completion code deduplication" -a __fish_complete_gpg_command`
	`19`	`+function __fish_complete_gpg -a __fish_complete_gpg_command`
`19`	`20`	`if string match -q 'gpg (GnuPG) 1.*' ($__fish_complete_gpg_command --version 2>/dev/null)`
`20`	`21`	`complete -c $__fish_complete_gpg_command -l simple-sk-checksum -d 'Integrity protect secret keys by using a SHA-1 checksum'`
`21`	`22`	`complete -c $__fish_complete_gpg_command -l no-sig-create-check -d "Do not verify each signature right after creation"`