folx

README

Folx

We think mankind humankind needs help to communicate with greater inclusion.

Folx helps you identify language on the web or in a text file that may harm inclusion and diversity goals, and suggests alternative phrases where appropriate.

Folx is powered by the Google Natural Language API and features over 1000 customisable language rules across 5 categories:

• Gender
• Race and Ethnicity
• Disability
• LGBTQ
• Cliches

Folx was inspired by these great projects, and we gratefully used some of their rule files as a base:

• https://github.com/amperser/proselint
• https://github.com/errata-ai/vale

Folx is made with ❤ in the United Kingdom.

Installation

From Source

Folx is built with Go and requires the Go tool chain to build. Check it out at https://golang.org/ Folx uses the go modules feature. You can fetch the Folx package with:

go get github.com/thecolngroup/folx

The Folx Command Line App is in:

./cmd/folx/

A Powershell build script is also available to inject the build info into the binary:

./build/cmd/folx/gobuild-folxcmd.ps1

Download Binary

For Windows 64-bit only a binary is available to save the fuss of building from source.

See the Releases page https://github.com/thecolngroup/folx/releases

Clone the repo (with all files and folders to get correct directory structure and rule files)

Run folx.exe with the working directory set as:

./cmd/folx/

Usage

Folx analyses text against a customisable rule book, in order to identify terms and phrases that may reduce the impact of writing by way of micro aggression, bias, confusion, or outright offence.

Folx suggests alternative language (where appropriate) and provides references and examples to find out more.

Folx uses the Google Natural Language API for its lexical analysis. This dependency enables advanced rule features such as identifying entities and parts of speech. Read more here: https://cloud.google.com/natural-language/

Prerequisites

In order to connect to the Google Natural Language API the app, and the package tests assume a valid GCP credential is available.

You can learn how to create a GCP key for use with Folx here: https://cloud.google.com/natural-language/docs/setup

The command line app will attempt to load a .env file in the working directory which points to your local key file.

The .env file should contain the following:

GOOGLE_APPLICATION_CREDENTIALS={Path to your GCP project key file}

Rule Book

The Folx Rule Book currently contains over 1000 rules across 5 categories, each category has its own .yml file:

• Gender
• Race and Ethnicity
• Disability
• LGBTQ
• Cliches

You can view the rule files (in .yml format) in:

./cmd/folx/rules/

For guidance on rule format see:

.cmd/folx/rules/example/alice-in-wonderland.yml

Folx Command Line App

Folx app accepts various command line arguments (flags). Every flag is optional with sensible defaults provided. Use the flag -help for guidance and to see defaults.

folx -help

Folx will always write folx.log to the local working directory with various diagnostic and error messages.

The results of each analysis will be saved to the given report path with the names:

folx-summary.csv
folx-result.csv

If the files are already present they will be appended with the new output. The summary file gives execution info and sum totals. The result file contains a line for each instance of a failed rule in the given source.

Example to analyse a local text file

folx -source "./corpus/alice-in-wonderland.txt"

Example to analyse a web page

folx -mode "page" -source "https://github.com/blog"

Example to analyse a web site with all optional flags

folx -mode "site" -source "https://thecolngroup.com" -rulepath "./rules/" -reportpath "./report/thecolngroup.com/"

Web site analysis is throttled so not to overload a web site with requests.

Folx will only crawl pages within the domain of the given URL, and ignore articles which have less than 40 chars in order to reduce crawl time and API cost.

Roadmap

• Create a web app to enable easier file analysis
• Add further rules

Support

hello@thecolngroup.com

License

Copyright 2019 The Coln Group