1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
|
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Contributing To Fish — fish-shell 4.2.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=4da8bbd6" />
<link rel="stylesheet" type="text/css" href="_static/pydoctheme.css?v=f89b4716" />
<script src="_static/documentation_options.js?v=6fb65176"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="License" href="license.html" />
<link rel="prev" title="Terminal Compatibility" href="terminal-compatibility.html" />
<link rel="shortcut icon" type="image/png" href="_static/fish.png" />
</head><body><div id="fmain">
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-this"><a href="">Contributing To Fish</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="index.html">Documents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently asked questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="interactive.html">Interactive use</a></li>
<li class="toctree-l1"><a class="reference internal" href="language.html">The fish language</a></li>
<li class="toctree-l1"><a class="reference internal" href="commands.html">Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="fish_for_bash_users.html">Fish for bash users</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="completions.html">Writing your own completions</a></li>
<li class="toctree-l1"><a class="reference internal" href="prompt.html">Writing your own prompt</a></li>
<li class="toctree-l1"><a class="reference internal" href="design.html">Design</a></li>
<li class="toctree-l1"><a class="reference internal" href="relnotes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="terminal-compatibility.html">Terminal Compatibility</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contributing To Fish</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<div>
<h4><a href="index.html">Sections</a></h4>
<ul>
<li><a class="reference internal" href="#">Contributing To Fish</a><ul>
<li><a class="reference internal" href="#mailing-list">Mailing List</a></li>
<li><a class="reference internal" href="#github">GitHub</a></li>
<li><a class="reference internal" href="#guidelines">Guidelines</a></li>
<li><a class="reference internal" href="#contributing-completions">Contributing completions</a></li>
<li><a class="reference internal" href="#contributing-documentation">Contributing documentation</a></li>
<li><a class="reference internal" href="#code-style">Code Style</a><ul>
<li><a class="reference internal" href="#fish-script-style-guide">Fish Script Style Guide</a><ul>
<li><a class="reference internal" href="#configuring-your-editor-for-fish-scripts">Configuring Your Editor for Fish Scripts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#minimum-supported-rust-version-msrv-policy">Minimum Supported Rust Version (MSRV) Policy</a></li>
</ul>
</li>
<li><a class="reference internal" href="#testing">Testing</a><ul>
<li><a class="reference internal" href="#local-testing">Local testing</a></li>
</ul>
</li>
<li><a class="reference internal" href="#contributing-translations">Contributing Translations</a><ul>
<li><a class="reference internal" href="#adding-translations-for-a-new-language">Adding translations for a new language</a></li>
<li><a class="reference internal" href="#modifying-existing-translations">Modifying existing translations</a></li>
<li><a class="reference internal" href="#editing-po-files">Editing PO files</a></li>
<li><a class="reference internal" href="#modifications-to-strings-in-source-files">Modifications to strings in source files</a></li>
<li><a class="reference internal" href="#setting-code-up-for-translations">Setting Code Up For Translations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#updating-dependencies">Updating Dependencies</a></li>
<li><a class="reference internal" href="#versioning">Versioning</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="contributing-to-fish">
<h1>Contributing To Fish<a class="headerlink" href="#contributing-to-fish" title="Link to this heading">¶</a></h1>
<p>This document tells you how you can contribute to fish.</p>
<p>Fish is free and open source software, distributed under the terms of the GPLv2.</p>
<p>Contributions are welcome, and there are many ways to contribute!</p>
<p>Whether you want to change some of the core Rust source, enhance or add a completion script or function,
improve the documentation or translate something, this document will tell you how.</p>
<section id="mailing-list">
<h2>Mailing List<a class="headerlink" href="#mailing-list" title="Link to this heading">¶</a></h2>
<p>Send patches to the public mailing list: <a class="reference external" href="mailto:~krobelus/fish-shell%40lists.sr.ht">mailto:~krobelus/fish-shell<span>@</span>lists<span>.</span>sr<span>.</span>ht</a>.
Archives are available at <a class="reference external" href="https://lists.sr.ht/~krobelus/fish-shell/">https://lists.sr.ht/~krobelus/fish-shell/</a>.</p>
</section>
<section id="github">
<h2>GitHub<a class="headerlink" href="#github" title="Link to this heading">¶</a></h2>
<p>Fish is available on Github, at <a class="reference external" href="https://github.com/fish-shell/fish-shell">https://github.com/fish-shell/fish-shell</a>.</p>
<p>First, you’ll need an account there, and you’ll need a git clone of fish.
Fork it on Github and then run:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">git</span><span class="w"> </span><span class="no">clone</span><span class="w"> </span><span class="no">https://github.com/</span><span class="p"><USERNAME>/fish-shell.git</span>
</pre></div>
</div>
<p>This will create a copy of the fish repository in the directory fish-shell in your current working directory.</p>
<p>Also, for most changes you want to run the tests and so you’d get a setup to compile fish.
For that, you’ll require:</p>
<ul class="simple">
<li><p>Rust - when in doubt, try rustup</p></li>
<li><p>CMake</p></li>
<li><p>PCRE2 (headers and libraries) - optional, this will be downloaded if missing</p></li>
<li><p>gettext (only the msgfmt tool) - optional, for translation support</p></li>
<li><p>Sphinx - optional, to build the documentation</p></li>
</ul>
<p>Of course not everything is required always - if you just want to contribute something to the documentation you’ll just need Sphinx,
and if the change is very simple and obvious you can just send it in. Use your judgement!</p>
<p>Once you have your changes, open a pull request on <a class="reference external" href="https://github.com/fish-shell/fish-shell/pulls">https://github.com/fish-shell/fish-shell/pulls</a>.</p>
</section>
<section id="guidelines">
<h2>Guidelines<a class="headerlink" href="#guidelines" title="Link to this heading">¶</a></h2>
<p>In short:</p>
<ul class="simple">
<li><p>Be conservative in what you need (keep to the agreed minimum supported Rust version, limit new dependencies)</p></li>
<li><p>Use automated tools to help you (<code class="docutils literal notranslate"><span class="pre">build_tools/check.sh</span></code>)</p></li>
</ul>
</section>
<section id="contributing-completions">
<h2>Contributing completions<a class="headerlink" href="#contributing-completions" title="Link to this heading">¶</a></h2>
<p>Completion scripts are the most common contribution to fish, and they are very welcome.</p>
<p>In general, we’ll take all well-written completion scripts for a command that is publicly available.
This means no private tools or personal scripts, and we do reserve the right to reject for other reasons.</p>
<p>Before you try to contribute them to fish, consider if the authors of the tool you are completing want to maintain the script instead.
Often that makes more sense, specifically because they can add new options to the script immediately once they add them,
and don’t have to maintain one completion script for multiple versions. If the authors no longer wish to maintain the script,
they can of course always contact the fish maintainers to hand it over, preferably by opening a PR.
This isn’t a requirement - if the authors don’t want to maintain it, or you simply don’t want to contact them,
you can contribute your script to fish.</p>
<p>Completion scripts should</p>
<ol class="arabic simple">
<li><p>Use as few dependencies as possible - try to use fish’s builtins like <code class="docutils literal notranslate"><span class="pre">string</span></code> instead of <code class="docutils literal notranslate"><span class="pre">grep</span></code> and <code class="docutils literal notranslate"><span class="pre">awk</span></code>,
use <code class="docutils literal notranslate"><span class="pre">python</span></code> to read json instead of <code class="docutils literal notranslate"><span class="pre">jq</span></code> (because it’s already a soft dependency for fish’s tools)</p></li>
<li><p>If it uses a common unix tool, use POSIX-compatible invocations - ideally it would work on GNU/Linux, macOS, the BSDs and other systems</p></li>
<li><p>Option and argument descriptions should be kept short.
The shorter the description, the more likely it is that fish can use more columns.</p></li>
<li><p>Function names should start with <code class="docutils literal notranslate"><span class="pre">__fish</span></code>, and functions should be kept in the completion file unless they’re used elsewhere.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">fish_indent</span></code> on your script.</p></li>
<li><p>Try not to use minor convenience features right after they are available in fish - we do try to keep completion scripts backportable.
If something has a real impact on the correctness or performance, feel free to use it,
but if it is just a shortcut, please leave it.</p></li>
</ol>
<p>Put your completion script into share/completions/name-of-command.fish. If you have multiple commands, you need multiple files.</p>
<p>If you want to add tests, you probably want to add a littlecheck test. See below for details.</p>
</section>
<section id="contributing-documentation">
<h2>Contributing documentation<a class="headerlink" href="#contributing-documentation" title="Link to this heading">¶</a></h2>
<p>The documentation is stored in <code class="docutils literal notranslate"><span class="pre">doc_src/</span></code>, and written in ReStructured Text and built with Sphinx.</p>
<p>To build it locally, run from the main fish-shell directory:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">sphinx-build</span><span class="w"> </span><span class="no">-j</span><span class="w"> </span><span class="no">8</span><span class="w"> </span><span class="no">-b</span><span class="w"> </span><span class="no">html</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">doc_src/</span><span class="w"> </span><span class="no">/tmp/fish-doc/</span>
</pre></div>
</div>
<p>which will build the docs as html in /tmp/fish-doc. You can open it in a browser and see that it looks okay.</p>
<p>The builtins and various functions shipped with fish are documented in doc_src/cmds/.</p>
</section>
<section id="code-style">
<h2>Code Style<a class="headerlink" href="#code-style" title="Link to this heading">¶</a></h2>
<p>For formatting, we use:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">rustfmt</span></code> for Rust</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_indent</span></code> (shipped with fish) for fish script</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ruff</span> <span class="pre">format</span></code> for Python</p></li>
</ul>
<p>To reformat files, there is a script</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">build_tools/style.fish</span><span class="w"> </span><span class="no">--all</span>
<span class="nf">build_tools/style.fish</span><span class="w"> </span><span class="no">somefile.rs</span><span class="w"> </span><span class="no">some.fish</span>
</pre></div>
</div>
<section id="fish-script-style-guide">
<h3>Fish Script Style Guide<a class="headerlink" href="#fish-script-style-guide" title="Link to this heading">¶</a></h3>
<ol class="arabic simple">
<li><p>All fish scripts, such as those in the <em>share/functions</em> and <em>tests</em>
directories, should be formatted using the <code class="docutils literal notranslate"><span class="pre">fish_indent</span></code> command.</p></li>
<li><p>Function names should be in all lowercase with words separated by
underscores. Private functions should begin with an underscore. The
first word should be <code class="docutils literal notranslate"><span class="pre">fish</span></code> if the function is unique to fish.</p></li>
<li><p>The first word of global variable names should generally be <code class="docutils literal notranslate"><span class="pre">fish</span></code>
for public vars or <code class="docutils literal notranslate"><span class="pre">_fish</span></code> for private vars to minimize the
possibility of name clashes with user defined vars.</p></li>
</ol>
<section id="configuring-your-editor-for-fish-scripts">
<h4>Configuring Your Editor for Fish Scripts<a class="headerlink" href="#configuring-your-editor-for-fish-scripts" title="Link to this heading">¶</a></h4>
<p>If you use Vim: Install <a class="reference external" href="https://github.com/dag/vim-fish">vim-fish</a>,
make sure you have syntax and filetype functionality in <code class="docutils literal notranslate"><span class="pre">~/.vimrc</span></code>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">syntax</span><span class="w"> </span><span class="no">enable</span>
<span class="nf">filetype</span><span class="w"> </span><span class="no">plugin</span><span class="w"> </span><span class="no">indent</span><span class="w"> </span><span class="no">on</span>
</pre></div>
</div>
<p>Then turn on some options for nicer display of fish scripts in
<code class="docutils literal notranslate"><span class="pre">~/.vim/ftplugin/fish.vim</span></code>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="s2">" Set up :make to use fish for syntax checking.</span>
<span class="s2">compiler fish</span>
<span class="s2">"</span><span class="w"> </span><span class="no">Set</span><span class="w"> </span><span class="no">this</span><span class="w"> </span><span class="no">to</span><span class="w"> </span><span class="no">have</span><span class="w"> </span><span class="no">long</span><span class="w"> </span><span class="no">lines</span><span class="w"> </span><span class="no">wrap</span><span class="w"> </span><span class="no">inside</span><span class="w"> </span><span class="no">comments.</span>
<span class="nf">setlocal</span><span class="w"> </span><span class="no">textwidth=79</span>
<span class="gr">"</span><span class="s2"> Enable folding of block structures in fish.</span>
<span class="s2">setlocal foldmethod=expr</span>
</pre></div>
</div>
<p>If you use Emacs: Install
<a class="reference external" href="https://github.com/wwwjfy/emacs-fish">fish-mode</a> (also available in
melpa and melpa-stable) and <code class="docutils literal notranslate"><span class="pre">(setq-default</span> <span class="pre">indent-tabs-mode</span> <span class="pre">nil)</span></code> for
it (via a hook or in <code class="docutils literal notranslate"><span class="pre">use-package</span></code>s “:init” block). It can also be
made to run fish_indent via e.g.</p>
<div class="highlight-elisp notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nv">add-hook</span><span class="w"> </span><span class="ss">'fish-mode-hook</span><span class="w"> </span><span class="p">(</span><span class="nb">lambda</span><span class="w"> </span><span class="p">()</span>
<span class="w"> </span><span class="p">(</span><span class="nv">add-hook</span><span class="w"> </span><span class="ss">'before-save-hook</span><span class="w"> </span><span class="ss">'fish_indent-before-save</span><span class="p">)))</span>
</pre></div>
</div>
</section>
</section>
<section id="minimum-supported-rust-version-msrv-policy">
<h3>Minimum Supported Rust Version (MSRV) Policy<a class="headerlink" href="#minimum-supported-rust-version-msrv-policy" title="Link to this heading">¶</a></h3>
<p>We support at least the version of <code class="docutils literal notranslate"><span class="pre">rustc</span></code> available in Debian Stable.</p>
</section>
</section>
<section id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Link to this heading">¶</a></h2>
<p>The source code for fish includes a large collection of tests. If you
are making any changes to fish, running these tests is a good way to make
sure the behaviour remains consistent and regressions are not
introduced. Even if you don’t run the tests on your machine, they will
still be run via Github Actions.</p>
<p>You are strongly encouraged to add tests when changing the functionality
of fish, especially if you are fixing a bug to help ensure there are no
regressions in the future (i.e., we don’t reintroduce the bug).</p>
<p>Unit tests live next to the implementation in Rust source files, in inline submodules (<code class="docutils literal notranslate"><span class="pre">mod</span> <span class="pre">tests</span> <span class="pre">{}</span></code>).</p>
<p>System tests live in <code class="docutils literal notranslate"><span class="pre">tests/</span></code>:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">tests/checks</span></code> are run by <a class="reference external" href="https://github.com/ridiculousfish/littlecheck">littlecheck</a>
and test noninteractive (script) behavior,
except for <code class="docutils literal notranslate"><span class="pre">tests/checks/tmux-*</span></code> which test interactive scenarios.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tests/pexpects</span></code> tests interactive scenarios using <a class="reference external" href="https://pexpect.readthedocs.io/en/stable/">pexpect</a></p></li>
</ul>
<p>When in doubt, the bulk of the tests should be added as a littlecheck test in tests/checks, as they are the easiest to modify and run, and much faster and more dependable than pexpect tests.
The syntax is fairly self-explanatory.
It’s a fish script with the expected output in <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">CHECK:</span></code> or <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">CHECKERR:</span></code> (for stderr) comments.
If your littlecheck test has a specific dependency, use <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">REQUIRE:</span> <span class="pre">...</span></code> with a POSIX sh script.</p>
<p>The pexpect tests are written in Python and can simulate input and output to/from a terminal, so they are needed for anything that needs actual interactivity.
The runner is in tests/pexpect_helper.py, in case you need to modify something there.</p>
<p>These tests can be run via the tests/test_driver.py Python script, which will set up the environment.
It sets up a temporary $HOME and also uses it as the current directory, so you do not need to create a temporary directory in them.</p>
<p>If you need a command to do something weird to test something, maybe add it to the <code class="docutils literal notranslate"><span class="pre">fish_test_helper</span></code> binary (in <code class="docutils literal notranslate"><span class="pre">tests/fish_test_helper.c</span></code>).</p>
<section id="local-testing">
<h3>Local testing<a class="headerlink" href="#local-testing" title="Link to this heading">¶</a></h3>
<p>The tests can be run on your local system:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">cargo</span><span class="w"> </span><span class="no">build</span>
<span class="c"># Run unit tests</span>
<span class="nf">cargo</span><span class="w"> </span><span class="no">test</span>
<span class="c"># Run system tests</span>
<span class="nf">tests/test_driver.py</span><span class="w"> </span><span class="no">target/debug</span>
<span class="c"># Run a specific system test.</span>
<span class="nf">tests/test_driver.py</span><span class="w"> </span><span class="no">target/debug</span><span class="w"> </span><span class="no">tests/checks/abbr.fish</span>
</pre></div>
</div>
<p>Here, the first argument to test_driver.py refers to a directory with <code class="docutils literal notranslate"><span class="pre">fish</span></code>, <code class="docutils literal notranslate"><span class="pre">fish_indent</span></code> and <code class="docutils literal notranslate"><span class="pre">fish_key_reader</span></code> in it.
In this example we’re in the root of the workspace and have run <code class="docutils literal notranslate"><span class="pre">cargo</span> <span class="pre">build</span></code> without <code class="docutils literal notranslate"><span class="pre">--release</span></code>, so it’s a debug build.</p>
<p>To run all tests and linters, use:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">build_tools/check.sh</span>
</pre></div>
</div>
</section>
</section>
<section id="contributing-translations">
<h2>Contributing Translations<a class="headerlink" href="#contributing-translations" title="Link to this heading">¶</a></h2>
<p>Fish uses GNU gettext to translate messages from English to other languages.
We use custom tools for extracting messages from source files and to localize at runtime.
This means that we do not have a runtime dependency on the gettext library.
It also means that some features are not supported, such as message context and plurals.
We also expect all files to be UTF-8-encoded.
In practice, this should not matter much for contributing translations.</p>
<p>Translation sources are
stored in the <code class="docutils literal notranslate"><span class="pre">po</span></code> directory, named <code class="docutils literal notranslate"><span class="pre">ll_CC.po</span></code>, where <code class="docutils literal notranslate"><span class="pre">ll</span></code> is the
two (or possibly three) letter ISO 639-1 language code of the target language
(e.g. <code class="docutils literal notranslate"><span class="pre">pt</span></code> for Portuguese). <code class="docutils literal notranslate"><span class="pre">CC</span></code> is an ISO 3166 country/territory code,
(e.g. <code class="docutils literal notranslate"><span class="pre">BR</span></code> for Brazil).
An example for a valid name is <code class="docutils literal notranslate"><span class="pre">pt_BR.po</span></code>, indicating Brazilian Portuguese.
These are the files you will interact with when adding translations.</p>
<section id="adding-translations-for-a-new-language">
<h3>Adding translations for a new language<a class="headerlink" href="#adding-translations-for-a-new-language" title="Link to this heading">¶</a></h3>
<p>Creating new translations requires the Gettext tools.
More specifically, you will need <code class="docutils literal notranslate"><span class="pre">msguniq</span></code> and <code class="docutils literal notranslate"><span class="pre">msgmerge</span></code> for creating translations for a new
language.
To create a new translation, run:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">build_tools/update_translations.fish</span><span class="w"> </span><span class="no">po/ll_CC.po</span>
</pre></div>
</div>
<p>This will create a new PO file containing all messages available for translation.
If the file already exists, it will be updated.</p>
<p>After modifying a PO file, you can recompile fish, and it will integrate the modifications you made.
This requires that the <code class="docutils literal notranslate"><span class="pre">msgfmt</span></code> utility is installed (comes as part of <code class="docutils literal notranslate"><span class="pre">gettext</span></code>).
It is important that the <code class="docutils literal notranslate"><span class="pre">localize-messages</span></code> cargo feature is enabled, which it is by default.
You can explicitly enable it using:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">cargo</span><span class="w"> </span><span class="no">build</span><span class="w"> </span><span class="no">--features=localize-messages</span>
</pre></div>
</div>
<p>Use environment variables to tell fish which language to use, e.g.:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="no">LANG</span><span class="o">=</span><span class="no">pt_BR.utf8</span><span class="w"> </span><span class="nf">fish</span>
</pre></div>
</div>
<p>or within the running fish shell:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">LANG</span><span class="w"> </span><span class="no">pt_BR.utf8</span>
</pre></div>
</div>
<p>For more options regarding how to choose languages, see
<a class="reference external" href="https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html">the corresponding gettext documentation</a>.
One neat thing you can do is set a list of languages to check for translations in the order defined
using the <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> variable, e.g.:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">LANGUAGE</span><span class="w"> </span><span class="no">pt_BR</span><span class="w"> </span><span class="no">de_DE</span>
</pre></div>
</div>
<p>to try to translate messages to Portuguese, if that fails try German, and if that fails too you will
see the English version defined in the source code.</p>
</section>
<section id="modifying-existing-translations">
<h3>Modifying existing translations<a class="headerlink" href="#modifying-existing-translations" title="Link to this heading">¶</a></h3>
<p>If you want to work on translations for a language which already has a corresponding <code class="docutils literal notranslate"><span class="pre">po</span></code> file, it
is sufficient to edit this file. No other changes are necessary.</p>
<p>After recompiling fish, you should be able to see your translations in action. See the previous
section for details.</p>
</section>
<section id="editing-po-files">
<h3>Editing PO files<a class="headerlink" href="#editing-po-files" title="Link to this heading">¶</a></h3>
<p>Many tools are available for editing translation files, including
command-line and graphical user interface programs. For simple use, you can use your text editor.</p>
<p>Open up the PO file, for example <code class="docutils literal notranslate"><span class="pre">po/sv.po</span></code>, and you’ll see something like:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">msgid</span><span class="w"> </span><span class="s2">"%s: No suitable job\n"</span>
<span class="nf">msgstr</span><span class="w"> </span><span class="s2">""</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">msgid</span></code> here is the “name” of the string to translate, typically the English string to translate.
The second line (<code class="docutils literal notranslate"><span class="pre">msgstr</span></code>) is where your translation goes.</p>
<p>For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">msgid</span><span class="w"> </span><span class="s2">"%s: No suitable job\n"</span>
<span class="nf">msgstr</span><span class="w"> </span><span class="s2">"%s: Inget passande jobb\n"</span>
</pre></div>
</div>
<p>Any <code class="docutils literal notranslate"><span class="pre">%s</span></code> or <code class="docutils literal notranslate"><span class="pre">%d</span></code> are placeholders that fish will use for formatting at runtime. It is important that they match - the translated string should have the same placeholders in the same order.</p>
<p>Also any escaped characters, like that <code class="docutils literal notranslate"><span class="pre">\n</span></code> newline at the end, should be kept so the translation has the same behavior.</p>
<p>Our tests run <code class="docutils literal notranslate"><span class="pre">msgfmt</span> <span class="pre">--check-format</span> <span class="pre">/path/to/file</span></code>, so they would catch mismatched placeholders - otherwise fish would crash at runtime when the string is about to be used.</p>
<p>Be cautious about blindly updating an existing translation file.
<code class="docutils literal notranslate"><span class="pre">msgid</span></code> strings should never be updated manually, only by running the appropriate script.</p>
</section>
<section id="modifications-to-strings-in-source-files">
<h3>Modifications to strings in source files<a class="headerlink" href="#modifications-to-strings-in-source-files" title="Link to this heading">¶</a></h3>
<p>If a string changes in the sources, the old translations will no longer work.
They will be preserved in the PO files, but commented-out (starting with <code class="docutils literal notranslate"><span class="pre">#~</span></code>).
If you add/remove/change a translatable strings in a source file,
run <code class="docutils literal notranslate"><span class="pre">build_tools/update_translations.fish</span></code> to propagate this to all translation files (<code class="docutils literal notranslate"><span class="pre">po/*.po</span></code>).
This is only relevant for developers modifying the source files of fish or fish scripts.</p>
</section>
<section id="setting-code-up-for-translations">
<h3>Setting Code Up For Translations<a class="headerlink" href="#setting-code-up-for-translations" title="Link to this heading">¶</a></h3>
<p>All non-debug messages output for user consumption should be marked for
translation. In Rust, this requires the use of the <code class="docutils literal notranslate"><span class="pre">wgettext!</span></code> or <code class="docutils literal notranslate"><span class="pre">wgettext_fmt!</span></code>
macros:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">streams.out.append</span><span class="o">(</span><span class="nf">wgettext_fmt!</span><span class="o">(</span><span class="s2">"%s: There are no jobs\n"</span><span class="nf">, argv[0]</span><span class="o">))</span><span class="p">;</span>
</pre></div>
</div>
<p>All messages in fish script must be enclosed in single or double quote
characters for our message extraction script to find them.
They must also be translated via a command substitution. This means
that the following are <strong>not</strong> valid:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">_</span><span class="w"> </span><span class="no">hello</span><span class="o">)</span>
<span class="nf">_</span><span class="w"> </span><span class="s2">"goodbye"</span>
</pre></div>
</div>
<p>Above should be written like this instead:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">_</span><span class="w"> </span><span class="s2">"hello"</span><span class="o">)</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">_</span><span class="w"> </span><span class="s2">"goodbye"</span><span class="o">)</span>
</pre></div>
</div>
<p>You can use either single or double quotes to enclose the
message to be translated. You can also optionally include spaces after
the opening parentheses or before the closing parentheses.</p>
</section>
</section>
<section id="updating-dependencies">
<h2>Updating Dependencies<a class="headerlink" href="#updating-dependencies" title="Link to this heading">¶</a></h2>
<p>To update dependencies, run <code class="docutils literal notranslate"><span class="pre">build_tools/update-dependencies.sh</span></code>.
This currently requires <a class="reference external" href="https://github.com/updatecli/updatecli">updatecli</a> and a few other tools.</p>
</section>
<section id="versioning">
<h2>Versioning<a class="headerlink" href="#versioning" title="Link to this heading">¶</a></h2>
<p>The fish version is constructed by the <em>build_tools/git_version_gen.sh</em>
script. For developers the version is the branch name plus the output of
<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">describe</span> <span class="pre">--always</span> <span class="pre">--dirty</span></code>. Normally the main part of the version
will be the closest annotated tag. Which itself is usually the most
recent release number (e.g., <code class="docutils literal notranslate"><span class="pre">2.6.0</span></code>).</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-this"><a href="">Contributing To Fish</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="footer">
© Copyright fish-shell developers.
<br />
<a href="https://github.com/fish-shell/fish-shell/issues">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</div>
<script type="text/javascript">
FISH_DOCS_VERSION = "4.2";
function copy_to_clipboard(it) {
// Find the pre tag we're interested in.
var pre = it.target;
while (pre.tagName != "PRE") pre = pre.parentNode;
var txt = "";
// Cheesy: If we have a prompt,
// we only copy prompted lines,
// by splitting and matching and stuff
if (pre.querySelector('span.gp')) {
var texts= [];
for (var line of pre.innerText.split('\n')) {
if (line.match(/^>_?.*/)) {
texts.push(line.replace(/^>_?/, ""));
}
}
txt = texts.join("\n");
} else {
// Even cheesier: If we don't have a prompt, we remove the button text from the end.
var txt = pre.innerText.substring(0, pre.innerText.length - it.target.innerText.length).trim();
}
navigator.clipboard.writeText(txt).then(function() {
// Success - set the text to indicate it,
// then set it back after 2 seconds.
var span = pre.querySelector("button span");
if (span) {
var oldText = span.innerText;
span.innerText = "COPIED!";
setTimeout(function() {
span.innerText = oldText;
}, 2000);
}
}, function() {
});
}
(function () {
// Add copy buttons to all the codeblocks.
var codeblocks = document.querySelectorAll('div > pre');
var button = document.createElement('button');
var span = document.createElement('span');
span.innerText = "COPY";
button.appendChild(span);
for (var i of codeblocks) {
var newButton = button.cloneNode(true);
newButton.addEventListener('click', copy_to_clipboard);
i.appendChild(newButton);
}
})();
</script>
</body>
</html>
|
