Skip to content

Commit 07942c9

Browse files
HeyItsGilbertHeyItsGilbert
committed
feat(readme): ✨ Update README with detailed extension features and usage instructions
- Enhanced description of the extension's functionality. - Added sections for features, installation, development, and usage. - Improved clarity on how the extension integrates with PowerShell localization.
1 parent a7b67ab commit 07942c9

10 files changed

Lines changed: 961 additions & 63 deletions

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 PowerShellLocalization Contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎PACKAGING.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Extension Packaging and Installation
2+
3+
This document explains how to package and install the PowerShell Localization extension for development and testing purposes.
4+
5+
## Quick Start
6+
7+
### Option 1: PowerShell Script (Recommended)
8+
9+
```powershell
10+
.\package-and-install.ps1
11+
```
12+
13+
### Option 2: Batch File (Windows)
14+
15+
```cmd
16+
package-and-install.bat
17+
```
18+
19+
### Option 3: NPM Scripts
20+
21+
```bash
22+
# Package and install
23+
yarn package-install
24+
25+
# Package only (skip installation)
26+
yarn package-only
27+
28+
# Package using vsce directly
29+
yarn package
30+
```
31+
32+
## Script Features
33+
34+
The `package-and-install.ps1` script provides the following functionality:
35+
36+
- ✅ **Dependency Check**: Automatically installs `vsce` if not present
37+
- 🧹 **Clean Build**: Removes previous builds and packages
38+
- 🔨 **Compilation**: Compiles TypeScript source code
39+
- 🔍 **Linting**: Runs ESLint for code quality
40+
- 📦 **Packaging**: Creates a `.vsix` extension package
41+
- 🚀 **Installation**: Installs the extension in VS Code
42+
43+
## Script Parameters
44+
45+
```powershell
46+
# Package and install (default)
47+
.\package-and-install.ps1
48+
49+
# Package only, skip installation
50+
.\package-and-install.ps1 -SkipInstall
51+
52+
# Force installation even if already installed
53+
.\package-and-install.ps1 -Force
54+
55+
# Combine parameters
56+
.\package-and-install.ps1 -SkipInstall -Force
57+
```
58+
59+
## Manual Steps
60+
61+
If you prefer to run the steps manually:
62+
63+
1. **Install vsce** (if not already installed):
64+
65+
```bash
66+
npm install -g @vscode/vsce
67+
```
68+
69+
2. **Install dependencies**:
70+
71+
```bash
72+
yarn install
73+
```
74+
75+
3. **Compile TypeScript**:
76+
77+
```bash
78+
yarn run compile
79+
```
80+
81+
4. **Package extension**:
82+
83+
```bash
84+
vsce package
85+
```
86+
87+
5. **Install extension**:
88+
89+
```bash
90+
code --install-extension powershelllocalization-*.vsix
91+
```
92+
93+
## Troubleshooting
94+
95+
### vsce Installation Issues
96+
97+
If `vsce` installation fails, try:
98+
99+
```bash
100+
npm install -g @vscode/vsce --force
101+
```
102+
103+
### PowerShell Execution Policy
104+
105+
If you get execution policy errors, run:
106+
107+
```powershell
108+
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser
109+
```
110+
111+
### Extension Not Loading
112+
113+
After installation:
114+
115+
1. Reload VS Code (`Ctrl+Shift+P` → "Developer: Reload Window")
116+
2. Open a PowerShell file (`.ps1`, `.psm1`, or `.psd1`)
117+
3. Check that the extension is active in the Extensions panel
118+
119+
### Clean Installation
120+
121+
To completely clean and reinstall:
122+
123+
```powershell
124+
# Remove old packages
125+
Remove-Item *.vsix -Force
126+
127+
# Clean compiled output
128+
Remove-Item -Recurse out -Force
129+
130+
# Run full package and install
131+
.\package-and-install.ps1 -Force
132+
```
133+
134+
## Development Workflow
135+
136+
For active development, you can use the watch mode:
137+
138+
```bash
139+
# Start TypeScript compiler in watch mode
140+
yarn run watch
141+
```
142+
143+
Then use F5 in VS Code to launch the Extension Development Host for testing.
144+
145+
## Files Generated
146+
147+
- `powershelllocalization-*.vsix` - The packaged extension file
148+
- `out/` - Compiled JavaScript output
149+
- Extension logs in VS Code Developer Tools
150+
151+
## Next Steps
152+
153+
After successful installation:
154+
155+
1. Open a PowerShell module with localization files
156+
2. Verify that localization variables show inline values
157+
3. Test the extension configuration in VS Code settings

‎README.md‎

Lines changed: 34 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,63 @@
1-
# powershelllocalization README
1+
# PowerShell Localization
22

3-
This is the README for your extension "powershelllocalization". After writing up a brief description, we recommend including the following sections.
3+
A Visual Studio Code extension that displays PowerShell localization variable values inline in your editor, making it easier to develop and debug internationalized PowerShell modules.
44

55
## Features
66

7-
Describe specific features of your extension including screenshots of your extension in action. Image paths are relative to this README file.
7+
- **Inline Value Display**: View localization variable values directly in your PowerShell files
8+
- **Real-time Updates**: Values update automatically when localization files change
9+
- **Multi-language Support**: Works with all localization files (en-US, fr-FR, etc.)
10+
- **PowerShell Integration**: Seamlessly integrates with PowerShell module development workflow
811

9-
For example if there is an image subfolder under your extension project workspace:
12+
## How It Works
1013

11-
\!\[feature X\]\(images/feature-x.png\)
12-
13-
> Tip: Many popular extensions utilize animations. This is an excellent way to show off your extension! We recommend short, focused animations that are easy to follow.
14+
The extension automatically scans for PowerShell modules (`.psm1` files) and their associated localization data files (`.psd1` files in language-specific folders like `en-US/`, `fr-FR/`, etc.). When you reference localization variables in your PowerShell code using `$LocalizedData.VariableName`, the extension will display the actual localized value inline.
1415

1516
## Requirements
1617

17-
If you have any requirements or dependencies, add a section describing those and how to install and configure them.
18+
- Visual Studio Code 1.102.0 or higher
19+
- PowerShell modules with localization data files
1820

1921
## Extension Settings
2022

21-
Include if your extension adds any VS Code settings through the `contributes.configuration` extension point.
22-
23-
For example:
24-
2523
This extension contributes the following settings:
2624

27-
* `myExtension.enable`: Enable/disable this extension.
28-
* `myExtension.thing`: Set to `blah` to do something.
29-
30-
## Known Issues
31-
32-
Calling out known issues can help limit users opening duplicate issues against your extension.
33-
34-
## Release Notes
35-
36-
Users appreciate release notes as you update your extension.
37-
38-
### 1.0.0
39-
40-
Initial release of ...
25+
- `powershelllocalization.enableInlineValues`: Enable/disable inline display of localization variable values
4126

42-
### 1.0.1
27+
## Installation
4328

44-
Fixed issue #.
29+
1. Package the extension using the provided scripts
30+
2. Install the `.vsix` file in VS Code
31+
3. Reload VS Code to activate the extension
4532

46-
### 1.1.0
33+
## Development
4734

48-
Added features X, Y, and Z.
35+
To build and install this extension:
4936

50-
---
37+
```bash
38+
# Using PowerShell script
39+
.\package-and-install.ps1
5140

52-
## Following extension guidelines
41+
# Using npm scripts
42+
yarn package-install
5343

54-
Ensure that you've read through the extensions guidelines and follow the best practices for creating your extension.
44+
# Package only
45+
yarn package-only
46+
```
5547

56-
* [Extension Guidelines](https://code.visualstudio.com/api/references/extension-guidelines)
48+
## Usage
5749

58-
## Working with Markdown
50+
1. Open a PowerShell module (`.psm1` file) that uses localization
51+
2. Ensure you have localization data files in language folders (e.g., `en-US/ModuleName.psd1`)
52+
3. Reference localization variables in your code: `$LocalizedData.MessageText`
53+
4. The extension will display the actual localized values inline
5954

60-
You can author your README using Visual Studio Code. Here are some useful editor keyboard shortcuts:
55+
## Contributing
6156

62-
* Split the editor (`Cmd+\` on macOS or `Ctrl+\` on Windows and Linux).
63-
* Toggle preview (`Shift+Cmd+V` on macOS or `Shift+Ctrl+V` on Windows and Linux).
64-
* Press `Ctrl+Space` (Windows, Linux, macOS) to see a list of Markdown snippets.
57+
Contributions are welcome! Please feel free to submit issues and pull requests.
6558

66-
## For more information
59+
## License
6760

68-
* [Visual Studio Code's Markdown Support](http://code.visualstudio.com/docs/languages/markdown)
69-
* [Markdown Syntax Reference](https://help.github.com/articles/markdown-basics/)
61+
MIT
7062

7163
**Enjoy!**

‎cspell.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"version": "0.2",
3+
"ignorePaths": [],
4+
"dictionaryDefinitions": [],
5+
"dictionaries": [
6+
"powershell"
7+
],
8+
"words": [
9+
"psinclusive",
10+
"powershelllocalization"
11+
],
12+
"ignoreWords": [],
13+
"import": []
14+
}

‎package-and-install.bat‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
@echo off
2+
setlocal enabledelayedexpansion
3+
4+
echo.
5+
echo ========================================
6+
echo PowerShell Localization Extension Build
7+
echo ========================================
8+
echo.
9+
10+
:: Check if PowerShell is available
11+
where pwsh >nul 2>&1
12+
if %errorlevel% neq 0 (
13+
echo PowerShell Core not found. Trying Windows PowerShell...
14+
where powershell >nul 2>&1
15+
if %errorlevel% neq 0 (
16+
echo ERROR: No PowerShell found. Please install PowerShell Core.
17+
pause
18+
exit /b 1
19+
)
20+
set PWSH_CMD=powershell
21+
) else (
22+
set PWSH_CMD=pwsh
23+
)
24+
25+
:: Run the PowerShell script
26+
echo Running packaging script...
27+
%PWSH_CMD% -ExecutionPolicy Bypass -File "%~dp0package-and-install.ps1" %*
28+
29+
if %errorlevel% neq 0 (
30+
echo.
31+
echo ERROR: Packaging failed!
32+
pause
33+
exit /b %errorlevel%
34+
)
35+
36+
echo.
37+
echo SUCCESS: Extension packaged and installed!
38+
pause

0 commit comments

Comments
 (0)